1400 lines
58 KiB
HTML
1400 lines
58 KiB
HTML
<!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>
|