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',
host: 'example.org'
});
// without new keyword
var uri = URI("example.org");
The following parts can be specified in an object:
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 #
});
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
var uri = new URI("http://user:[email protected]/foo/hello.html");
// get username
uri.username(); // returns string "user"
// set username
uri.username("user"); // returns the URI instance for chaining
var uri = new URI("http://user:[email protected]/foo/hello.html");
// get password
uri.password(); // returns string "pass"
// set password
uri.password("user"); // returns the URI instance for chaining
var uri = new URI("http://example.org/foo/hello.html");
// get protocol
uri.hostname(); // returns string
// set protocol
uri.hostname("example.org"); // returns the URI instance for chaining
NOTE: .hostname() returns the actual hostname, whereas .host() returns the hostname including the port
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
NOTE: although the port may be considered an integer, within URI it is a string.
var uri = new URI("http://example.org/foo/hello.html");
// get host
uri.host(); // returns string "example.org"
// set host
uri.host("example.org:80"); // returns the URI instance for chaining
NOTE: .hostname() returns the actual hostname, whereas .host() returns the hostname including the port
Authority is comprised of username, password, hostname and port
var uri = new URI("http://user:[email protected]:88/foo/hello.html");
// get authority
uri.authority(); // returns string "user:[email protected]:88"
// set authority
uri.authority("user:[email protected]:80"); // returns the URI instance for chaining
NOTE: .authority() will reset any of username, password and port if they're not specified.
.domain() is a convenience method that returns example.org from the hostname www.example.org.
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
NOTE: .domain() will throw an error if you pass it an empty string.
.tld() is a convenience method that returns org from the hostname www.example.org.
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
NOTE: .tld() will throw an error if you pass it an empty string or use it on an IP-host.
.path() is an alias of .pathname()
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
.directory() is an convenience method for mutating the directory part of a path
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"
.filename() is an convenience method for mutating the filename part of a path
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/bar/world.xml"
.suffix() is an convenience method for mutating the filename part of a path
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"
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.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"
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 #)
// .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"
.addQuery() is an alias of .addSearch()
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"
.removeQuery() is an alias of .removeSearch()
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"); // 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.addSearch(["hello", "foo"]);
// uri == "?mine=true"
// remove multiple values with value filter
uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&b=2&b=3");
uri.addSearch({hello: "world", foo: undefined, a: ["1", "3"]});
// uri == "?hello=mars&mine=true&b=2"
executes normalizeHostname(), normalizePort(), normalizePath(), normalizeSearch(), normalizeHash()
For IDN conversion punycode.js must be available (bundled in URI.js). For IPv6-best-notation conversion IPv6.js must be available (bundled in URI.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/"
Removes the port, if it's the default for the given protocol (http: 80, https: 443, ftp: 21).
The list of default ports can be modified at URI.defaultPorts
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"
.normalizePath() is an alias of .normalizePathname(), they resolve relative hierarchies
var uri = new URI("/hello/foo/woo/.././../world.html");
// normalize path
uri.normalizePathname(); // returns the URI instance for chaining
// uri == "/hello/world.html"
Turns ?&foo=bar&&foo=bar&foo=baz& into ?foo=bar&foo=baz and removes ? if there is no query string.
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"
removes # if there is no hash
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"
.relativeTo() compares to paths an makes one relative to the other
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"
.relativeTo() and .absoluteTo() reverse each other.
.absoluteTo() makes a relative path absolute based on another path
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"
.relativeTo() and .absoluteTo() reverse each other.