<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>URI.js - API Documentation</title>
<meta name="description" content="URI.js is a Javascript library for working with URLs." />
<script src="jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="prettify/prettify.js" type="text/javascript"></script>
<script src="screen.js" type="text/javascript"></script>
<link href="screen.css" rel="stylesheet" type="text/css" />
<link href="prettify/prettify.sunburst.css" rel="stylesheet" type="text/css" />
<script src="src/URI.min.js" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-8922143-3']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<a id="github-forkme" href="https://github.com/medialize/URI.js"><img src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
<div id="container">
<h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1>
<ul class="menu">
<li><a href="/URI.js/">Intro</a></li>
<li><a href="/URI.js/about-uris.html">Understanding URIs</a></li>
<li class="active"><a href="docs.html">API-Documentation</a></li>
<li><a href="jquery-uri-plugin.html">jQuery Plugin</a></li>
<li><a href="uri-template.html">URI Template</a></li>
<li><a href="build.html">Build</a></li>
<li><a href="http://rodneyrehm.de/en/">Author</a></li>
</ul>
<ul class="toc">
<li>
<a href="#constructor">Constructing an URI</a>
<ul>
<li><a href="#clone">cloning an URI instance</a></li>
<li><a href="#href">href()</a></li>
<li><a href="#toString">toString(), valueOf()</a></li>
</ul>
</li>
<li>
Working with URI parts
<ul>
<li><a href="#accessors-protocol">protocol(), scheme()</a></li>
<li><a href="#accessors-username">username()</a></li>
<li><a href="#accessors-password">password()</a></li>
<li><a href="#accessors-hostname">hostname()</a></li>
<li><a href="#accessors-port">port()</a></li>
<li><a href="#accessors-host">host()</a></li>
<li><a href="#accessors-userinfo">userinfo()</a></li>
<li><a href="#accessors-authority">authority()</a></li>
<li><a href="#accessors-origin">origin()</a></li>
<li><a href="#accessors-subdomain">subdomain()</a></li>
<li><a href="#accessors-domain">domain()</a></li>
<li><a href="#accessors-tld">tld()</a></li>
<li><a href="#accessors-pathname">pathname(), path()</a></li>
<li><a href="#accessors-directory">directory()</a></li>
<li><a href="#accessors-filename">filename()</a></li>
<li><a href="#accessors-suffix">suffix()</a></li>
<li><a href="#accessors-segment">segment()</a></li>
<li><a href="#accessors-segmentCoded">segmentCoded()</a></li>
<li><a href="#accessors-search">search(), query()</a></li>
<li><a href="#accessors-hash">hash(), fragment()</a></li>
<li><a href="#accessors-resource">resource()</a></li>
<li><a href="#is">determine URL types</a></li>
</ul>
</li>
<li>
Working with the query string
<ul>
<li><a href="#accessors-search">search(), query()</a></li>
<li><a href="#search-set">setSearch(), setQuery()</a></li>
<li><a href="#search-add">addSearch(), addQuery()</a></li>
<li><a href="#search-remove">removeSearch(), removeQuery()</a></li>
<li><a href="#search-has">hasSearch(), hasQuery()</a></li>
</ul>
</li>
<li>
<a href="#fragment-abuse">Working with the Fragment (Hash)</a>
<ul>
<li><a href="#fragment-abuse-query">Data in Fragments (Hash)</a></li>
<li><a href="#fragment-abuse-uri">URLs in Fragments (Hash)</a></li>
</ul>
</li>
<li>
Normalizing URLs
<ul>
<li><a href="#normalize">normalize()</a></li>
<li><a href="#normalize-protocol">normalizeProtocol()</a></li>
<li><a href="#normalize-host">normalizeHostname()</a></li>
<li><a href="#normalize-port">normalizePort()</a></li>
<li><a href="#normalize-path">normalizePathname(), normalizePath()</a></li>
<li><a href="#normalize-search">normalizeSearch(), normalizeQuery()</a></li>
<li><a href="#normalize-hash">normalizeHash(), normalizeFragment()</a></li>
</ul>
</li>
<li>
Charsets / Encodings
<ul>
<li><a href="#iso8859">iso8859()</a></li>
<li><a href="#unicode">unicode()</a></li>
</ul>
</li>
<li><a href="#readable">readable()</a></li>
<li>
Relative and Absolute URLs
<ul>
<li><a href="#relativeto">relativeTo()</a></li>
<li><a href="#absoluteto">absoluteTo()</a></li>
<li><a href="#static-joinPaths">URI.URI.joinPaths()</a></li>
</ul>
</li>
<li>
Comparing URLs
<ul>
<li><a href="#equals">equals()</a></li>
</ul>
</li>
<li>
Parsing URLs
<ul>
<li><a href="#static-parse">URI.parse()</a></li>
<li><a href="#static-parseAuthority">URI.parseAuthority()</a></li>
<li><a href="#static-parseUserinfo">URI.parseUserinfo()</a></li>
<li><a href="#static-parseHost">URI.parseHost()</a></li>
<li><a href="#static-parseQuery">URI.parseQuery()</a></li>
</ul>
</li>
<li>
Serializing URLs
<ul>
<li><a href="#static-build">URI.build()</a></li>
<li><a href="#static-buildAuthority">URI.buildAuthority()</a></li>
<li><a href="#static-buildUserinfo">URI.buildUserinfo()</a></li>
<li><a href="#static-buildHost">URI.buildHost()</a></li>
<li><a href="#static-buildQuery">URI.buildQuery()</a></li>
</ul>
</li>
<li>
Encoding and Decoding URLs
<ul>
<li><a href="#static-encode">URI.encode()</a></li>
<li><a href="#static-decode">URI.decode()</a></li>
<li><a href="#static-encodeReserved">URI.encodeReserved()</a></li>
<li><a href="#static-encodeQuery">URI.encodeQuery()</a></li>
<li><a href="#static-decodeQuery">URI.decodeQuery()</a></li>
</ul>
</li>
<li>
Static Helper Functions
<ul>
<li><a href="#static-noConflict">URI.noConflict()</a></li>
<li><a href="#static-addQuery">URI.addQuery()</a></li>
<li><a href="#static-removeQuery">URI.removeQuery()</a></li>
<li><a href="#static-commonPath">URI.commonPath()</a></li>
<li><a href="#static-joinPaths">URI.joinPath()</a></li>
<li><a href="#static-withinString">URI.withinString()</a></li>
<li><a href="#static-iso8859">URI.iso8859()</a></li>
<li><a href="#static-unicode">URI.unicode()</a></li>
<li><a href="#static-expand">URI.expand()</a></li>
</ul>
</li>
</ul>
<h2 id="api-methods">URI.js API</h2>
<h3 id="constructor">URI Constructor</h3>
<pre class="prettyprint lang-js">var uri = new URI(); // same as new URI(location.href)
// string
var uri = new URI("http://example.org");
// URI object for cloning
var uri = new URI(new URI("http://example.org"));
// URI parts object
var uri = new URI({
protocol: "http",
hostname: "example.org"
});
// without new keyword
var uri = URI("http://example.org");
// resolving right in the constructor
var uri = URI("../foobar.html", "http://example.org/hello/world.html");
// which is exactly the same as
URI("../foobar.html").absoluteTo("http://example.org/hello/world.html");
// but specified in <a href="http://dvcs.w3.org/hg/url/raw-file/tip/Overview.html#constructor">URL constructor</a></pre>
<p>The following parts can be specified in an object:</p>
<pre class="prettyprint lang-js">var uri = new URI({
protocol: "http", // no trailing :
username: "user",
password: "pass",
hostname: "example.org",
port: "80", // string, please
// "path", not "pathname", sorry
path: "/foo/bar.html",
// "query", not "search", sorry
query: "foo=bar&bar=baz", // no leading ?
// "fragment", not "hash", sorry
fragment: "frag" // no leading #
});</pre>
<p>using only components of URIs:</p>
<pre class="prettyprint lang-js">// Look ma! I'm only working the pathname
var uri = new URI("some/directory/file.html");
// Look ma! I'm only working the query string
var uri = new URI("?foo=bar");
// Look ma! I'm only working the fragment / hash
var uri = new URI("#call-me-hash");
// and any combination of the above…</pre>
<p>using DOM elements:</p>
<pre class="prettyprint lang-js">var element = document.createElement('a');
element.href = 'http://example.org';
var uri = new URI(element);
// uri.domain() === 'example.org';</pre>
<pre class="prettyprint lang-html">The following DOM elements can be parsed:
<a href="...">
<blockquote cite="...">
<link href="...">
<base href="...">
<script src="...">
<form action="...">
<input type="image" src="...">
<img src="...">
<area href="...">
<iframe src="...">
<embed src="...">
<source src="...">
<track src="...">
any other element yields URI("")
</pre>
<h3 id="clone">cloning URIs</h3>
<p>Get a copy of the current URI instance</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org");
var uri2 = uri.clone();
uri2.tld("com");
uri == "http://example.org/";
uri2 == "http://example.com/";</pre>
<h3 id="href">href()</h3>
<p>get and set the entire URI</p>
<pre class="prettyprint lang-js">var uri = URI("http://example.com");
uri.href() === "http://example.com/";
uri.href("ftp://google.org");
uri.toString() === "ftp://google.org/"</pre>
<h3 id="toString">toString(), valueOf()</h3>
<p>serialize the URI to string. <code>valueOf()</code> is an alias to <code>toString()</code>, as string is the base primitive.</p>
<pre class="prettyprint lang-js">var uri = URI("http://example.com");
var s = uri.toString();
typeof s === "string";
s === "http://example.com/";</pre>
<h3 id="accessors-protocol">protocol(), scheme()</h3>
<p>.scheme() is an alias of .protocol()</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get protocol
uri.protocol(); // returns string "http"
// set protocol
uri.protocol("ftp"); // returns the URI instance for chaining
// relative scheme
uri.protocol("");
uri.toString() === "//example.org/foo/hello.html";</pre>
<p class="note">Throws a <code>TypeError</code> on illegal input, that is anything but <code>[a-z0-9.+-]</code> and <code>[empty string]</code> and <code>null</code></p>
<h3 id="accessors-username">username()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org/foo/hello.html");
// get username
uri.username(); // returns string "user"
// set username
uri.username("user"); // returns the URI instance for chaining</pre>
<h3 id="accessors-password">password()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org/foo/hello.html");
// get password
uri.password(); // returns string "pass"
// set password
uri.password("user"); // returns the URI instance for chaining</pre>
<h3 id="accessors-hostname">hostname()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get hostname
uri.hostname(); // returns string
// set hostname
uri.hostname("example.org"); // returns the URI instance for chaining</pre>
<p class="note"><a href="#accessors-hostname">.hostname()</a> returns the actual hostname, whereas <a href="#accessors-host">.host()</a> returns the hostname including the port</p>
<h3 id="accessors-port">port()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org:8080/foo/hello.html");
// get port
uri.port(); // returns string "8080"
// set port
uri.port("80"); // returns the URI instance for chaining</pre>
<p class="note">although the port may be considered an integer, within URI it is a string.</p>
<p class="note">Throws a <code>TypeError</code> on illegal input</p>
<h3 id="accessors-host">host()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org:80/foo/hello.html");
// get host
uri.host(); // returns string "example.org:80"
// set host
uri.host("example.org:80"); // returns the URI instance for chaining</pre>
<p class="note"><a href="#accessors-hostname">.hostname()</a> returns the actual hostname, whereas <a href="#accessors-host">.host()</a> returns the hostname including the port</p>
<p class="note">Throws a <code>TypeError</code> if <code>path</code> is part of the input</p>
<h3 id="accessors-userinfo">userinfo()</h3>
<p>Userinfo is comprised of username and password</p>
<pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org:88/foo/hello.html");
// get userinfo
uri.userinfo(); // returns string "user:pass"
// set userinfo
uri.userinfo("user:pass"); // returns the URI instance for chaining</pre>
<h3 id="accessors-authority">authority()</h3>
<p>Authority is comprised of username, password, hostname and port</p>
<pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org:88/foo/hello.html");
// get authority
uri.authority(); // returns string "user:pass@example.org:88"
// set authority
uri.authority("user:pass@example.org:80"); // returns the URI instance for chaining</pre>
<p class="note">.authority() will reset any of username, password and port if they're not specified.</p>
<p class="note">Throws a <code>TypeError</code> if <code>path</code> is part of the input</p>
<h3 id="accessors-origin">origin()</h3>
<p>Origin is comprised of the scheme and authority.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.com/foo.html?q=hello");
// get origin
uri.origin(); // returns string "http://example.com"
// set origin
uri.origin('https://other.org'); // returns URI instance for chaining
// the URI will now have the string representation of:
// "https://other.org/foo.html?q=hello"</pre>
<p class="note">.origin() will reset the entire authority, including username, password and port if not specified in the new origin.</p>
<p class="note">.origin() will be empty if there is no authority.</p>
<p class="note">.origin() will be the same as .authority() (e.g. "example.org") if there is no scheme available.</p>
<h3 id="accessors-domain">domain()</h3>
<p>.domain() is a convenience method that returns <code>example.org</code> from the hostname <code>www.example.org</code>.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get domain
uri.domain(); // returns string "example.org"
// set domain
uri.domain("otherdomain.com"); // returns the URI instance for chaining
// Second Level Domain (SLD) Support (as of URI.js 1.5.0)
uri = new URI("http://example.co.uk/foo/hello.html");
uri.domain(); // return string "example.co.uk"
uri.domain(true); // return string "co.uk"</pre>
<p class="note"><code>.domain()</code> will throw an error if you pass it an empty string.</p>
<p class="note">Throws a <code>TypeError</code> on illegal input</p>
<h3 id="accessors-subdomain">subdomain()</h3>
<p>.subdomain() is a convenience method that returns <code>www</code> from the hostname <code>www.example.org</code>.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://www.example.org/foo/hello.html");
// get subdomain
uri.subdomain(); // returns string "www"
// set subdomain
uri.subdomain("other.subdomain"); // returns the URI instance for chaining</pre>
<p class="note">Throws a <code>TypeError</code> on illegal input</p>
<h3 id="accessors-tld">tld()</h3>
<p>.tld() is a convenience method that returns <code>org</code> from the hostname <code>www.example.org</code>.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get tld
uri.tld(); // returns string "org"
// set tld
uri.tld("com"); // returns the URI instance for chaining
// Second Level Domain (SLD) Support (as of URI.js 1.5.0)
uri = new URI("http://example.co.uk/foo/hello.html");
uri.tld(); // return string "co.uk"
uri.tld(true); // return string "uk"</pre>
<p class="note">Throws an <code>Error</code> if you pass it an empty string or use it on an IP-host.</p>
<h3 id="accessors-pathname">pathname(), path()</h3>
<p>.path() is an alias of .pathname()</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get pathname
uri.pathname(); // returns string "/foo/hello.html"
// set pathname
uri.pathname("/foo/hello.html"); // returns the URI instance for chaining
// will encode for you
uri.pathname("/hello world/");
uri.pathname() === "/hello%20world/";
// will decode for you
uri.pathname(true) === "/hello world/";
// will return empty string for empty paths, but:
URI("").path() === "";
URI("/").path() === "/";
URI("http://example.org").path() === "/";
</pre>
<h3 id="accessors-directory">directory()</h3>
<p>.directory() is an convenience method for mutating the directory part of a path</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get directory
uri.directory(); // returns string "/foo" (no trailing slash)
// set directory
uri.directory("/bar"); // returns the URI instance for chaining
// uri == "http://example.org/bar/hello.html"
// will encode for you
uri.directory("/hello world/");
uri.directory() === "/hello%20world";
// will decode for you
uri.directory(true) === "/hello world";
uri.href("http://example.com/foo").directory()
// -&t; "/"
uri.href("/foo").directory()
// -&t; "/"
uri.href("foo").directory()
// -&t; ""</pre>
<h3 id="accessors-filename">filename()</h3>
<p>.filename() is an convenience method for mutating the filename part of a path</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get filename
uri.filename(); // returns string "hello.html" (no leading slash)
// set filename
uri.filename("world.xml"); // returns the URI instance for chaining
// uri == "http://example.org/foo/world.xml"
// will encode for you
uri.filename("hello world.html");
uri.filename() === "hello%20world.html";
// will decode for you
uri.filename(true) === "hello world.html";</pre>
<p class="note">If you pass <code>../file.html</code>, the directory will be changed accordingly</p>
<h3 id="accessors-suffix">suffix()</h3>
<p>.suffix() is an convenience method for mutating the filename part of a path</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get suffix
uri.suffix(); // returns string "html" (no leading dot)
// set suffix
uri.suffix("xml"); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.xml"
// will encode for you
uri.suffix("würgh");
uri.suffix() === "w%C3%BCrgh";
// will decode for you
uri.suffix(true) === "würgh";</pre>
<h3 id="accessors-segment">segment()</h3>
<p>.segment() allows convenient access to directory levels / URN segments within the path. See <a href="#accessors-segmentCoded">.segmentCoded()</a> for an interface that transparently encodes and decodes path segments.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
// get segments
uri.segment(); // returns array ["foo", "hello.html"]
// set segments
uri.segment(["foo", "bar", "foobar.html"]); // -> http://example.org/foo/bar/foobar.html
// get specific level
uri.segment(0); // returns "foo"
uri.segment(1); // returns "bar"
uri.segment(-1); // returns "foobar.html"
// set specific level
uri.segment(0, "bar"); // -> http://example.org/bar/bar/foobar.html
// remove specific level
uri.segment(0, ""); // -> http://example.org/bar/foobar.html
// append level
uri.segment("appendthis"); // -> http://example.org/bar/foobar.html/appendthis</pre>
<h3 id="accessors-segmentCoded">segmentCoded()</h3>
<p>.segmentCoded() works the same way <a href="#accessors-segment">.segment()</a> does, with the difference of transparently encoding and decoding values.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello%20world.html");
// get segments
uri.segmentCoded(); // returns array ["foo", "hello world.html"]
// set segments
uri.segmentCoded(["foo", "bar", "foo bar.html"]); // -> http://example.org/foo/bar/foo%20bar.html
// get specific level
uri.segmentCoded(0); // returns "foo"
uri.segmentCoded(1); // returns "bar"
uri.segmentCoded(-1); // returns "foo bar.html"
// set specific level
uri.segmentCoded(0, "bar bam"); // -> http://example.org/bar%20bam/bar/foobar.html
// remove specific level
uri.segmentCoded(0, ""); // -> http://example.org/bar/foobar.html
// append level
uri.segmentCoded("append this"); // -> http://example.org/bar/foobar.html/append%20this</pre>
<h3 id="accessors-search">search(), query()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html?foo=bar&bar=baz");
// get search
uri.search(); // returns string "?foo=bar&bar=baz" (leading ?)
// get query
uri.query(); // returns string "foo=bar&bar=baz" (no leading ?)
// .query() and .search() behave the same for the following:
// set search
uri.search("?foo=bar&bar=baz"); // returns the URI instance for chaining
uri.search("foo=bar&bar=baz"); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.html?foo=bar&bar=baz"
// remove query
uri.search(""); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.html"
// get data map:
uri.search(true); // returns { foo: "bar", hello : ["world", "mars"] }
// set data map:
uri.search({ foo: "bar", hello : ["world", "mars"] });
// uri == "http://example.org/bar/world.html?foo=bar&hello=world&hello=mars"
// overwrite data through callback
uri.search(function(data) {
return { hello : "world" };
});
// uri == "http://example.org/bar/world.html?hello=world"
// augment data through callback
uri.search(function(data) {
data.foo = "bar";
});
// uri == "http://example.org/bar/world.html?hello=world&foo=bar"
// CAUTION: beware of arrays, the following are not quite the same
// If you're dealing with PHP, you probably want the latter…
uri.search("?foo=bar&bar=baz");
uri.search("?foo=bar[]&bar[]=baz");</pre>
<p>Note that names and values passed in an object are encoded automatically.
The object, resulting from parsing the query string, contains decoded values</p>
<p>Hint: If you're using jQuery, have a look at their <a href="http://api.jquery.com/serialize/">.serialize()</a> function.</p>
<h3 id="accessors-hash">hash(), fragment()</h3>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html#world");
// get hash
uri.hash(); // returns string "#world" (leading #)
// get fragment
uri.fragment(); // returns string "world" (no leading #)
// remove fragment
uri.fragment(""); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.html"
// .hash() and .fragment() behave the same for the following:
// set hash
uri.hash("#mars"); // returns the URI instance for chaining
uri.hash("mars"); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.xml#mars"</pre>
<h3 id="accessors-resource">resource()</h3>
<p>Resource is comprised of path, query and fragment</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html?query=string#hash");
// get resource
uri.resource(); // returns string "/foo/hello.html?query=string#hash"
// set resource
uri.resource("/mars.txt?query=foo#other"); // returns the URI instance for chaining</pre>
<p class="note"><code>.resource()</code> will reset any of path, query and fragment if they're not specified.</p>
<h3 id="is">is()</h3>
<p>.is() tells what a URL is. It responds with a boolean and can be asked the following questions:</p>
<dl>
<dt><code>relative</code></dt><dd><code>true</code> if URL doesn't have a hostname</dd>
<dt><code>absolute</code></dt><dd><code>true</code> if URL has a hostname</dd>
<dt><code>urn</code></dt><dd><code>true</code> if URI looks like a URN</dd>
<dt><code>url</code></dt><dd><code>true</code> if URI is a URL</dd>
<dt><code>domain</code>, <code>name</code></dt><dd><code>true</code> if hostname is not an IP</dd>
<dt><code>sld</code></dt><dd><code>true</code> if hostname is a second level domain (i.e. "example.co.uk")</dd>
<dt><code>idn</code></dt><dd><code>true</code> if hostname contains non-alphanumeric characters and is not an IP</dd>
<dt><code>punycode</code></dt><dd><code>true</code> if hostname contains <code>xn--</code></dd>
<dt><code>ip</code></dt><dd><code>true</code> if hostname is IPv4 or IPv6</dd>
<dt><code>ip4</code>, <code>ipv4</code>, <code>inet4</code></dt><dd><code>true</code> if hostname is IPv4</dd>
<dt><code>ip6</code>, <code>ipv6</code>, <code>inet6</code></dt><dd><code>true</code> if hostname is IPv6</dd>
</dl>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/");
uri.is("relative") === false;
uri.is("absolute") === true;
uri.is("urn") === false;
uri.is("url") === true;
uri.is("name") === true;
uri.is("sld") === false;
uri.is("punycode") === false;
uri.is("IDN") === false; // case doesn't matter
uri.is("idn") === false; // case doesn't matter
uri.is("ip") === false;
var uri = new URI("http://123.123.123.123/");
uri.is("relative") === false;
uri.is("absolute") === true;
uri.is("urn") === false;
uri.is("url") === true;
uri.is("name") === false;
uri.is("sld") === false;
uri.is("IP") === true;
uri.is("IPv4") === true;
uri.is("IPv6") === false;
var uri = new URI("http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/");
uri.is("IP") === true;
uri.is("IPv4") === false;
uri.is("IPv6") === true;
var uri = new URI("/hello/world.html");
uri.is("relative") === true;
uri.is("absolute") === false;
uri.is("urn") === false;
uri.is("url") === true;
uri.is("name") === false;
uri.is("IP") === false;
var uri = new URI("http://example.co.uk/");
uri.is("name") === true;
uri.is("sld") === true;
var uri = new URI("mailto:mail@example.org");
uri.is("relative") === false;
uri.is("absolute") === false;
uri.is("urn") === true;
uri.is("url") === false;
uri.is("name") === false;
uri.is("sld") === false;
uri.is("punycode") === false;
uri.is("idn") === false;
uri.is("ip") === false;</pre>
<h2 id="querystrings">Working with the query string</h2>
<h3 id="search-set">setSearch(), setQuery()</h3>
<p>.setQuery() is an alias of .setSearch()</p>
<pre class="prettyprint lang-js">var uri = new URI("?hello=world");
uri.setSearch("hello", "mars"); // returns the URI instance for chaining
// uri == "?hello=mars"
uri.setSearch({ foo: "bar", goodbye : ["world", "mars"] });
// uri == "?hello=mars&foo=bar&goodbye=world&goodbye=mars"
uri.setSearch("goodbye", "sun");
// uri == "?hello=mars&foo=bar&goodbye=sun"
// CAUTION: beware of arrays, the following are not quite the same
// If you're dealing with PHP, you probably want the latter…
uri.setSearch("foo", ["bar", "baz"]);
uri.setSearch("foo[]", ["bar", "baz"]);</pre>
<p>Note that names and values passed in are encoded automatically.</p>
<h3 id="search-add">addSearch(), addQuery()</h3>
<p>.addQuery() is an alias of .addSearch()</p>
<pre class="prettyprint lang-js">var uri = new URI("?hello=world");
uri.addSearch("hello", "mars"); // returns the URI instance for chaining
// uri == "?hello=world&hello=mars"
uri.addSearch({ foo: "bar", goodbye : ["world", "mars"] });
// uri == "?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars"
uri.addSearch("no-value");
// uri == "?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars&no-value"
// CAUTION: beware of arrays, the following are not quite the same
// If you're dealing with PHP, you probably want the latter…
uri.addSearch("foo", ["bar", "baz"]);
uri.addSearch("foo[]", ["bar", "baz"]);</pre>
<p>Note that names and values passed in are encoded automatically.</p>
<h3 id="search-remove">removeSearch(), removeQuery()</h3>
<p>.removeQuery() is an alias of .removeSearch()</p>
<pre class="prettyprint lang-js">var uri = new URI("?hello=world&hello=mars&foo=bar");
// remove an attribute
uri.removeSearch("hello"); // returns the URI instance for chaining
// uri == "?foo=bar"
// remove an attribute with value filter
uri.search("?hello=world&hello=mars&foo=bar");
uri.removeSearch("hello", "world"); // returns the URI instance for chaining
// uri == "?hello=mars&foo=bar"
// remove multiple values
uri.search("?hello=world&hello=mars&foo=bar&mine=true");
uri.removeSearch(["hello", "foo"]);
// uri == "?mine=true"
// remove multiple values with value filter
uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&a=2&a=3");
uri.removeSearch({hello: "world", foo: undefined, a: ["1", "3"]});
// uri == "?hello=mars&mine=true&a=2"
// remove multiple values with RegExp
uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&a=2&a=3");
uri.removeSearch(/^hello/);
// uri == "?foo=bar&mine=true&a=1&a=2&a=3"
// filter values with RegExp
uri.search("?foo=bar&foo=baz&foo=bam&obj=bam&bar=bar&bar=baz&bar=bam");
uri.removeSearch('foo', /[rz]$/);
// uri == "?foo=bam&obj=bam&bar=bar&bar=baz&bar=bam"</pre>
<h3 id="search-has">hasSearch(), hasQuery()</h3>
<p>.hasQuery() is an alias of .hasSearch(). The method checks the existence and value of a given parameter within the query string.</p>
<pre class="prettyprint lang-js">var uri = URI("?string=bar&list=one&list=two&number=123&null&empty=");
// check if parameter exists (regardless of value)
uri.hasQuery("string") === true;
uri.hasQuery("nono") === false;
// check if parameter has a truthy / falsy value
uri.hasQuery("string", true) === true;
uri.hasQuery("string", false) === false;
uri.hasQuery("empty", true) === false;
uri.hasQuery("empty", false) === true;
// check if parameter has a given value
uri.hasQuery("string", "bar") === true;
uri.hasQuery("number", 123) === true;
// check if value is contained in parameter list
uri.hasQuery("list", "two", true) === true;
uri.hasQuery("list", ["two"], true) === true;
uri.hasQuery("list", "three", true) === false;
uri.hasQuery("list", ["two", "three"], true) === false;
uri.hasQuery("list", /ne$/, true) === true;
// check if parameter matches an expression
uri.hasQuery("string", /ar$/) === true;
// check if parameter name matches an expression
uri.hasQuery(/^str/) === true;
// check if parameter name matches an expression and value exists
uri.hasQuery(/^li/, "two") === true;
// check by comparison function
uri.hasQuery("string", function(value, name, data) {
// value === "bar";
// name === "string";
// data === uri.query(true);
return true;
}) === true;</pre>
<h2 id="fragment-abuse">Working with the Fragment (Hash)</h2>
<p>
There are virtually no limits to what you might do with fragments (hash).
Every system has their own bag of tricks.
As a result URI.js cannot offer any of the following tools right out of the box.
The most common <em>abuse of fragments</em> are storing URLs or query string like data.
</p>
<p>
Usually a prefix is used to identify data with special meaning. This prefix can be pretty much what you want.
For URIs it's usually <code>!</code> and for query-like data it often is <code>?</code>.
But they don't have to, which is why you can define a global default: <code>URI.fragmentPrefix = "$";</code>
</p>
<h3 id="fragment-abuse-query">Query String Fragments</h3>
<p>The file <a href="https://github.com/medialize/URI.js/blob/gh-pages/src/URI.fragmentQuery.js">src/URI.fragmentQuery.js</a> is a "plugin" that allows you to store data in hashes in the same manner the .query() functions provide.</p>
<pre class="prettyprint lang-js">var uri = new URI("#?hello=world");
uri.addFragment("hello", "mars"); // returns the URI instance for chaining
// uri == "#?hello=world&hello=mars"
// to change the fragment prefix on an instance level:
uri.fragmentPrefix("!");
// to change the fragment prefix on a global level:
URI.fragmentPrefix = "!";</pre>
<h3 id="fragment-abuse-uri">URL Fragments</h3>
<p>The file <a href="https://github.com/medialize/URI.js/blob/gh-pages/src/URI.fragmentURI.js">src/URI.fragmentURI.js</a> is a "plugin" that allows you to store URLs in hashes.</p>
<pre class="prettyprint lang-js">var uri = URI("http://example.org/#!/foo/bar/baz.html");
var furi = uri.fragment(true);
// manipulating the fragment URI
furi.pathname() === "/foo/bar/baz.html";
furi.pathname("/hello.html");
// has direct effect on the actual URI
uri.toString() === "http://example.org/#!/hello.html"
// to change the fragment prefix on an instance level:
uri.fragmentPrefix("?");
// to change the fragment prefix on a global level:
URI.fragmentPrefix = "?";</pre>
<h2 id="normalizing">Normalizing URLs</h2>
<h3 id="normalize">normalize()</h3>
<p>executes normalizeProtocol(), normalizeHostname(), normalizePort(), normalizePath(), normalizeSearch(), normalizeHash()</p>
<h3 id="normalize-protocol">normalizeProtocol()</h3>
<pre class="prettyprint lang-js">var uri = new URI("hTTp://www.example.org/");
// normalize protocol
uri.normalizeProtocol(); // returns the URI instance for chaining
// uri == "http://www.example.org/"</pre>
<h3 id="normalize-host">normalizeHostname()</h3>
<p>For IDN conversion <a href="https://github.com/bestiejs/punycode.js">punycode.js</a> must be available (bundled in URI.js).
For IPv6-best-notation conversion IPv6.js must be available (bundled in URI.js). Also lower-cases hostnames.</p>
<pre class="prettyprint lang-js">var uri = new URI("http://www.exämple.org/");
// normalize IDN host
uri.normalizeHostname(); // returns the URI instance for chaining
// uri == "http://www.xn--exmple-cua.org/"
// normalize IPv6 host
uri.hostname("fe80:0000:0000:0000:0204:61ff:fe9d:f156");
uri.normalizeHostname(); // returns the URI instance for chaining
// uri == "http://fe80::204:61ff:fe9d:f156/"
// normalize hostname to lower case
uri.hostname("wWw.eXample.Org");
uri.normalizeHostname(); // returns the URI instance for chaining
// uri == "http://www.example.org/"</pre>
<p>There is no .normalizeHost(), as <a href="#accessors-host">.host()</a> is a property comprised of <a href="#accessors-hostname">.hostname()</a> and <a href="#accessors-port">.port()</a></p>
<h3 id="normalize-port">normalizePort()</h3>
<p>Removes the port, if it's the default for the given protocol (http: 80, https: 443, ftp: 21).</p>
<p>The list of default ports can be modified at <code>URI.defaultPorts</code></p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org:80/foo.html");
// normalize port
uri.normalizePort(); // returns the URI instance for chaining
// uri == "http://example.org/foo.html"</pre>
<h3 id="normalize-path">normalizePathname(), normalizePath()</h3>
<p>.normalizePath() is an alias of .normalizePathname(), they resolve relative hierarchies</p>
<pre class="prettyprint lang-js">var uri = new URI("/hello/foo/woo/.././../world.html");
// normalize path
uri.normalizePathname(); // returns the URI instance for chaining
// uri == "/hello/world.html"</pre>
<h3 id="normalize-search">normalizeSearch(), normalizeQuery()</h3>
<p>Turns <code>?&foo=bar&&foo=bar&foo=baz&</code> into <code>?foo=bar&foo=baz</code> and removes ? if there is no query string.</p>
<pre class="prettyprint lang-js">var uri = new URI("?&foo=bar&&foo=bar&foo=baz&");
// normalize search
uri.normalizeSearch(); // returns the URI instance for chaining
// uri == "?foo=bar&foo=baz"</pre>
<h3 id="normalize-hash">normalizeHash(), normalizeFragment()</h3>
<p>removes # if there is no hash</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html#");
// normalize hash
uri.normalizeHash(); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.xml"</pre>
<h2 id="charsets">Charsets / Encodings</h2>
<h3 id="iso8859">iso8859()</h3>
<p>.iso8859() converts unicode-encoded escape sequences to ISO8859-encoded escape sequences. It does this by calling <a href="#normalize">.normalize()</a> internally.</p>
<pre class="prettyprint lang-js">var uri = new URI("/%C3%A4.html");
uri.iso8859(); // returns the URI instance for chaining
// uri == "/%E4.html"</pre>
<p class="note">You can make URI work with ISO8859 encoding by default by calling <a href="#static-iso8859">URI.iso8859()</a>.
<h3 id="unicode">unicode()</h3>
<p>.unicode() converts ISO8859-encoded escape sequences to unicode-encoded escape sequences. It does this by calling <a href="#normalize">.normalize()</a> internally.</p>
<pre class="prettyprint lang-js">var uri = new URI("/%E4.html");
uri.unicode(); // returns the URI instance for chaining
// uri == "/%C3%A4.html"</pre>
<h2 id="formatting">Formatting URLs</h2>
<h3 id="readable">readable()</h3>
<p>Formats URLs to be human readable (much like your browser does nowadays).</p>
<pre class="prettyprint lang-js">var uri = new URI("http://foo:bar@www.xn--exmple-cua.org/"
+ "hello%20world/ä.html?foo%5B%5D=b+är#fragment");
uri.readable() === "http://www.exämple.org/"
+ "hello world/ä.html?foo[]=b är#fragment";</pre>
<h2 id="relative-and-absolute">Relative and Absolute URLs</h2>
<h3 id="relativeto">relativeTo()</h3>
<p>.relativeTo() compares two <em>paths</em> and makes one relative to the other</p>
<pre class="prettyprint lang-js">var uri = new URI("/relative/path");
// make path relative
var relUri = uri.relativeTo("/relative/sub/foo/sub/file"); // returns a new URI instance
// relUri == "../../../path"
// absolute URLs are passed through unchanged
URI("http://example.org/world.html")
.relativeTo("http://google.com/baz");
// -> "http://example.org/world.html"
// absolute URLs relative to absolute URLs
// may resolve the protocol
URI("http://example.org/world.html")
.clone()
.authority("")
.relativeTo("http://google.com/baz");
// -> "//google.com/world.html"
// equal URLs are relative by empty string
URI("http://www.example.com:8080/dir/file")
.relativeTo('http://www.example.com:8080/dir/file');
// -> ""
// relative on fragment and query string as well
URI("http://www.example.com:8080/dir/file?foo=bar#abcd")
.relativeTo('http://www.example.com:8080/dir/file');
// -> "?foo=bar#abcd"</pre>
<p>.relativeTo() and .absoluteTo() reverse each other.</p>
<h3 id="absoluteto">absoluteTo()</h3>
<p>.absoluteTo() makes a <em>relative path</em> absolute based on another path</p>
<pre class="prettyprint lang-js">var uri = new URI("../../../path");
// make path absolute
var relUri = uri.absoluteTo("/relative/sub/foo/sub/file"); // returns a new URI instance
// relUri == "/relative/path"
// resolves protocols
var u = new URI('//example.com/path');
u.absoluteTo('https://example.com');
// -> "https://example.com/path"
var u = new URI('//example.com/path');
u.absoluteTo('https://');
// -> "https://example.com/path"</pre>
<p>.relativeTo() and .absoluteTo() reverse each other.</p>
<h2 id="comparison">Comparing URLs</h2>
<h3 id="equals">equals()</h3>
<p>.equals() determines if the given URLs are the same - disregarding default ports, capitalization, dot-pathnames, query-parameter order, etc.</p>
<pre class="prettyprint lang-js">var a = "http://example.org/foo/bar.html"
+ "?foo=bar&hello=world&hello=mars#fragment";
var b;
// normalizing URI before comparison:
b = "http://exAMPle.org:80/foo/../foo/bar.html"
+ "?foo=bar&hello=world&hello=mars#fragment";
a !== b;
URI(a).equals(b) === true;
// comparing query string parameters:
b = "http://example.org/foo/bar.html"
+ "?hello=mars&foo=bar&hello=world&#fragment";
a !== b;
URI(a).equals(b) === true;
// shorthand for comparing to window.location.href:
URI(a).equals();</pre>
<h2 id="parsing-urls">Parsing URLs</h2>
<h3 id="static-parse">URI.parse(<em>string</em> url)</h3>
<p>parses a string into its URI components. returns an object containing the found components</p>
<pre class="prettyprint lang-js">var result = URI.parse("http://example.org/foo.html");
result === {
protocol: "http",
username: null,
password: null,
hostname: "example.org",
port: null,
path: "/foo.html",
query: null,
fragment: null
};</pre>
<h3 id="static-parseAuthority">URI.parseAuthority(<em>string</em> url, <em>object</em> parts)</h3>
<p>parses a string's beginning into its URI components username, password, hostname, port.
Found components are appended to the <code>parts</code> parameter.
Remaining string is returned</p>
<pre class="prettyprint lang-js">var parts = {};
var result = URI.parseAuthority("user:pass@example.org:8080/foo.html", parts);
result === "/foo.html";
parts === {
username: "user",
password: "pass",
hostname: "example.org",
port: "8080"
};</pre>
<h3 id="static-parseUserinfo">URI.parseUserinfo(<em>string</em> url, <em>object</em> parts)</h3>
<p>parses a string's beginning into its URI components username, password.
Found components are appended to the <code>parts</code> parameter.
Remaining string is returned</p>
<pre class="prettyprint lang-js">var parts = {};
var result = URI.parseUserinfo("user:pass@example.org:8080/foo.html", parts);
result === "example.org:8080/foo.html";
parts === {
username: "user",
password: "pass"
};</pre>
<h3 id="static-parseHost">URI.parseHost(<em>string</em> url, <em>object</em> parts)</h3>
<p>parses a string's beginning into its URI components hostname, port.
Found components are appended to the <code>parts</code> parameter.
Remaining string is returned</p>
<pre class="prettyprint lang-js">var parts = {};
var result = URI.parseHost("example.org:8080/foo.html", parts);
result === "/foo.html";
parts === {
hostname: "example.org",
port: "8080"
};</pre>
<h3 id="static-parseQuery">URI.parseQuery(<em>string</em> querystring)</h3>
<p>Parses the passed query string into an object. Returns object <code>{propertyName: propertyValue}</code></p>
<pre class="prettyprint lang-js">var result = URI.parseQuery("?foo=bar&hello=world&hello=mars&bam=&yup");
result === {
foo: "bar",
hello: ["world", "mars"],
bam: "",
yup: null
};</pre>
<h2 id="serializing-urls">Serializing URLs</h2>
<h3 id="static-build">URI.build(<em>object</em> parts)</h3>
<p>serializes the URI components passed in <code>parts</code> into a URI string</p>
<pre class="prettyprint lang-js">var parts = {
protocol: "http",
username: null,
password: null,
hostname: "example.org",
port: null,
path: "/foo.html",
query: null,
fragment: null
};
URI.build(parts) === "http://example.org/foo.html";</pre>
<h3 id="static-buildAuthority">URI.buildAuthority(<em>object</em> parts)</h3>
<p>serializes the URI components username, password, hostname, port passed in <code>parts</code> into a URI string</p>
<pre class="prettyprint lang-js">var parts = {
username: "user",
password: "pass",
hostname: "example.org",
port: "8080"
};
URI.buildAuthority(parts) === "user:pass@example.org:8080";</pre>
<h3 id="static-buildUserinfo">URI.buildUserinfo(<em>object</em> parts)</h3>
<p>serializes the URI components username, password passed in <code>parts</code> into a URI string</p>
<pre class="prettyprint lang-js">var parts = {
username: "user",
password: "pass"
};
URI.buildUserinfo(parts) === "user:pass@";</pre>
<h3 id="static-buildHost">URI.buildHost(<em>object</em> parts)</h3>
<p>serializes the URI components hostname, port passed in <code>parts</code> into a URI string</p>
<pre class="prettyprint lang-js">var parts = {
hostname: "example.org",
port: "8080"
};
URI.buildHost(parts) === "example.org:8080";</pre>
<h3 id="static-buildQuery">URI.buildQuery(<em>object</em> data, [<em>boolean</em> duplicateQueryParameters], [<em>boolean</em> escapeQuerySpace])</h3>
<p>serializes the query string parameters</p>
<pre class="prettyprint lang-js">var data = {
foo: "bar",
hello: ["world", "mars", "mars"],
bam: "",
yup: null,
removed: undefined
};
// Note: duplicate hello=mars is dropped (default behavior!)
URI.buildQuery(data) === "foo=bar&hello=world&hello=mars&bam=&yup";
// Note: duplicate hello=mars is preserved
URI.buildQuery(data, true) === "foo=bar&hello=world&hello=mars&hello=mars&bam=&yup";</pre>
<p>To preserve duplicate values, use URI.buildQuery() directly:</p>
<pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo.html?bar=baz");
var data = uri.query(true);
data.some = "new data";
uri.query(URI.buildQuery(data, true));
// you can also use the static <a href="#static-addQuery">URI.addQuery()</a> and <a href="#static-removeQuery">URI.removeQuery()</a>
URI.addQuery(data, "hello", "world");
uri.query(URI.buildQuery(data, true));</pre>
<p id="setting-duplicateQueryParameters">As of v1.8.0 you can configure query parameter de/duplication:</p>
<pre class="prettyprint lang-js">// make all new URI instances allow duplicates:
URI.duplicateQueryParameters = true; // default is false
// make a specific URI instance allow duplicates:
var withDuplicates = URI("?bar=1&bar=1")
.duplicateQueryParameters(true)
.normalizeQuery()
.toString();
// make a specific URI instance avoid duplicates (default):
var noDuplicates = URI("?bar=1&bar=1")
.duplicateQueryParameters(false)
.normalizeQuery()
.toString();
withDuplicates === "?bar=1&bar=1";
noDuplicates === "?bar=1";</pre>
<p id="setting-escapeQuerySpace">As of v1.11.0 you can configure query space en/decoding:</p>
<pre class="prettyprint lang-js">// prevent all new URI instances from escaping spaces in query strings:
URI.escapeQuerySpace = false; // default is true
// make a specific URI instance escape spaces in query:
var withPlus = URI("?bar=hello+world")
.escapeQuerySpace(true)
.query(true).bar;
// make a specific URI instance not escape spaces in query
var withPercent = URI("?bar=hello%20world")
.escapeQuerySpace(false)
.query(true).bar;
withPlus === "hello world";
withPercent === "hello world";</pre>
<h2 id="encoding-decoding">Encoding and Decoding URLs</h2>
<h3 id="static-encode">URI.encode()</h3>
<p>Encode an URI component with strict compliance to RFC3986</p>
<pre class="prettyprint lang-js">URI.encode("hä lo#w*rl:d!") === "h%C3%A4%20lo%23w%2Arl%3Ad%21";
// vs.
encodeURIComponent("hä lo#w*rl:d!") === "h%C3%A4%20lo%23w*rl%3Ad!";
// not how * and ! were not encoded</pre>
<h3 id="static-decode">URI.decode()</h3>
<p>Decode an URI component</p>
<pre class="prettyprint lang-js">URI.decode("h%C3%A4%20lo%23w%2Arl%3Ad%21") === "hä lo#w*rl:d!";
// note:
URI.decode === decodeURIComponent;</pre>
<h3 id="static-encodeReserved">URI.encodeReserved()</h3>
<p>Encode an URI component whilst preserving <a href="http://tools.ietf.org/html/rfc3986#section-2.2">reserved characters</a></p>
<pre class="prettyprint lang-js">URI.encodeReserved("ä:/?#[]@!$&'()*+,;=") === "%C3%A4:/?#[]@!$&'()*+,;=";
// vs.
URI.encode("ä:/?#[]@!$&'()*+,;=") ===
"%C3%A4%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D";</pre>
<h3 id="static-encodeQuery">URI.encodeQuery()</h3>
<p>Encode a query string component. Works like <a href="#static-encode">encode()</a>, except it handles <code>%20</code> as <code>+</code> (space) if <a href="#setting-escapeQuerySpace"><code>URI.escapeQuerySpace = true;</code></a>.</p>
<pre class="prettyprint lang-js">URI.escapeQuerySpace = true; // default
URI.encodeQuery(" ") === "+";
URI.escapeQuerySpace = false;
URI.encodeQuery(" ") === "%20";
// vs.
URI.encode(" ") === "%20";</pre>
<h3 id="static-decodeQuery">URI.decodeQuery()</h3>
<p>Decode a query string component. Works like <a href="#static-decode">decode()</a>, except it handles <code>+</code> as <code>%20</code> (space) if <a href="#setting-escapeQuerySpace"><code>URI.escapeQuerySpace = true;</code></a>.</p>
<pre class="prettyprint lang-js">URI.escapeQuerySpace = true; // default
URI.decodeQuery("+") === " ";
URI.escapeQuerySpace = false;
URI.decodeQuery("+") === "+";
// vs.
URI.decode("+") === "+";</pre>
<h2 id="static-functions">Static Helper Functions</h2>
<h3 id="static-noConflict">URI.noConflict()</h3>
<p>removes URI variables from global scope</p>
<pre class="prettyprint lang-js">// restores window.URI to its previous state and returns URI
URI.noConflict();
// restores the global variable to its previous state and returns the object itself
URITemplate.noConflict();
IPv6.noConflict();
SecondLevelDomains.noConflict();
// restore all objects and return them as a map {URI: ..., IPv6: ..., ....}
URI.noConflict(true);</pre>
<h3 id="static-addQuery">URI.addQuery()</h3>
<p>adds data to a map</p>
<pre class="prettyprint lang-js">var data = {};
URI.addQuery(data, "hello", "mars");
data === {hello: "mars"};
URI.addQuery(data, "hello", "world");
data === {hello: ["mars", "world"]};
URI.addQuery(data, {foo: "bar", goodbye : ["world", "mars"]});
data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};</pre>
<h3 id="static-removeQuery">URI.removeQuery()</h3>
<p>removes data from a map</p>
<pre class="prettyprint lang-js">var data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};
URI.removeQuery(data, "hello");
data === {foo: "bar", goodbye : ["world", "mars"]};
// remove an attribute with value filter
data = {hello: ["world", "mars"], foo: "bar"};
URI.removeQuery(data, "hello", "world");
data === {hello: ["mars"], foo: "bar"} // yes, still an array
// remove multiple values
data = {hello: ["world", "mars"], foo: "bar", mine: "true"}
URI.removeQuery(["hello", "foo"]);
data === {mine: "true"};
// remove multiple values with value filter
data = {hello: ["world", "mars"], foo: "bar", mine: "true", a: ["1", "2", "3"]}
URI.removeQuery({hello: "world", foo: undefined, a: ["1", "3"]});
data === {hello: ["mars"], mine: "true", a: ["2"]}</pre>
<h3 id="static-commonPath">URI.commonPath()</h3>
<p>URI.commonPath() determines the common base directory of two paths.</p>
<pre class="prettyprint lang-js">URI.commonPath("/foo/bar/baz.html", "/foo/bar/world.html");
// returns "/foo/bar/"
URI.commonPath("/foo/bar/baz.html", "/foo/bazz/world.html");
// returns "/foo/"
URI.commonPath("/foo/bar/baz.html", "/other/world.html");
// returns "/"
URI.commonPath("/foo", "bar");
// returns ""</pre>
<h3 id="static-joinPaths">URI.joinPath()</h3>
<p>URI.joinPath() composes a path from directory tokens.</p>
<pre class="prettyprint lang-js">URI.joinPaths('/a/b', '/c', 'd', '/e');
// returns URI("/a/b/c/d/e")
URI.joinPaths('a/b', 'http://example.com/c', new URI('d/'), '/e');
// returns URI("a/b/c/d/e")
URI.joinPaths('/a/');
// returns URI("/a/")
URI.joinPaths('');
// returns URI("")
URI.joinPaths('', 'a', '');
// returns URI("/a/")</pre>
<h3 id="static-withinString">URI.withinString()</h3>
<p>URI.withinString() identifies URIs within text, e.g. to translate them to <a>-Tags. (Obviously you'd want to put the urls inside the href-Attribute and escape them properly…)</p>
<p class="note">.withinString() only works on plain text, it will not work with HTML!</p>
<pre class="prettyprint lang-js">var source = "Hello www.example.com,\n"
+ "http://google.com is a search engine, like http://www.bing.com\n"
+ "http://exämple.org/foo.html?baz=la#bumm is an IDN URL,\n"
+ "http://123.123.123.123/foo.html is IPv4 and "
+ "http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/foobar.html is IPv6.\n"
+ "links can also be in parens (http://example.org) "
+ "or quotes »http://example.org«.";
var result = URI.withinString(source, function(url) {
// callback needs to return a string
// feel free to URI(url).normalize().toString() or something
return "<a>" + url + "</a>";
});
/* result is:
Hello <strong><a>www.example.com</a></strong>,
<strong><a>http://google.com</a></strong> is a search engine, like <strong><a>http://www.bing.com</a></strong>
<strong><a>http://exämple.org/foo.html?baz=la#bumm</a></strong> is an IDN URL,
<strong><a>http://123.123.123.123/foo.html</a></strong> is IPv4 and <strong><a>http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/foobar.html</a></strong> is IPv6.
links can also be in parens (<strong><a>http://example.org</a></strong>) or quotes »<strong><a>http://example.org</a></strong>«.
*/
// a proper replacement could look like the following:
var escapeHtml = function(string) {
return string
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;");
};
var result = URI.withinString(source, function(url) {
var uri = new URI(url);
uri.normalize();
return "<a href="" + escapeHtml(uri) + "">"
+ escapeHtml(uri.<a href="#readable">readable</a>()) + "</a>";
});
</pre>
<p>As of URI.js 1.12.0 withinString accepts the following parameters:</p>
<pre class="prettyprint lang-js">var source = "Hello www.example.com.";
var decorate = function(url) {
return "<code>" + url + "</code>";
};
var result = null;
// access to the original input text from the callback
URI.withinString(source, function(url, start, end, source) {
source.slice(start, end) === url;
return url;
});
// ignore certain URLs
source = "Hello www.example.com,\n"
+ "ohgodno://example.org/ is a a protocol we want ignored";
result = URI.withinString(source, decorate, {
ignore: /^ohgodno:/i
});
/* result is:
Hello <strong><code>www.example.com</code></strong>,
ohgodno://example.org/ is a a protocol we want ignored
*/
// ignore URLs in HTML
source = "Hello www.example.com,\n"
+ '<img src="http://example.org/image.png" alt=""> is HTML,\n'
+ "<a href='http://example.org/target.html'> is HTML</a>,\n"
+ "<a href=http://example.org/target.html> is HTML, too</a>.";
result = URI.withinString(source, decorate, {
ignoreHtml: true
});
/* result is:
Hello <strong><code>www.example.com</code></strong>,
<img src="http://example.org/image.png" alt=""> is HTML,
<a href='http://example.org/target.html'> is HTML</a>,
<a href=http://example.org/target.html> is HTML, too</a>
*/
// custom URI beginning pattern
source = "That example.com/ is just a domain";
result = URI.withinString(source, decorate, {
// "scheme://" or "www." or "domain.tld/"
start: /\b(?:([a-z][a-z0-9.+-]*:\/\/)|www\.|[a-z]+\.[a-z]{2,4}\/)/gi
});
/* result is:
That <strong><code>example.com/</code></strong> is just a domain
*/</pre>
<h3 id="static-iso8859">URI.iso8859()</h3>
<p>URI.iso8859() tells URI.js to use the older escape/unescape methods, for backwards compatibility with non-unicode platforms.</p>
<pre class="prettyprint lang-js">URI.iso8859();
var uri = new URI("http://example.org/foo/æ.html");
// http://example.org/foo/%E6.html</pre>
<h3 id="static-unicode">URI.unicode()</h3>
<p>URI.unicode() restores the default unicode-encoded URLs.</p>
<pre class="prettyprint lang-js">URI.unicode();
var uri = new URI("http://example.org/foo/æ.html");
// http://example.org/foo/%C3%A6.html</pre>
<h3 id="static-expand">URI.expand()</h3>
<p>URI.expand() is a convenience wrapper for <a href="uri-template.html"><code>URITemplate</code></a>.
While <code>URITemplate#expand</code> returns a string, <code>URI.expand()</code> returns an <code>URI</code> instance.</p>
<pre class="prettyprint lang-js">URI.expand("/foo/{var}/{iable}", {
"var": "bar",
"iable": "hello world.html"
});
// returns URI("/foo/bar/hello%20world.html")</pre>
</div>
</body>
</html>