diff options
Diffstat (limited to 'docs.html')
| -rw-r--r-- | docs.html | 1399 |
1 files changed, 1399 insertions, 0 deletions
diff --git a/docs.html b/docs.html new file mode 100644 index 000000000..31d58ed5d --- /dev/null +++ b/docs.html @@ -0,0 +1,1399 @@ +<!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> |