URI.js

- - - -

URI.js is a javascript library for working with URLs. It offers a "jQuery-style" API (Fluent Interface, Method Chaining) to read and write all regular components and a number of convenience methods like - .directory() and .authority().

URI.js offers simple, yet powerful ways of working with query string, has a number of URI-normalization functions and converts relative/absolute paths.

While URI.js provides a jQuery plugin. URI.js itself does not rely on jQuery. You don't need jQuery to use URI.js

- -

Examples

How do you like manipulating URLs the "jQuery-style"?

// mutating URLs
-URI("http://example.org/foo.html?hello=world")
-    .username("rodneyrehm") 
-        // -> http://rodneyrehm@example.org/foo.html?hello=world
-    .username("") 
-        // -> http://example.org/foo.html?hello=world
-    .directory("bar")
-        // -> http://example.org/bar/foo.html?hello=world
-    .suffix("xml")    
-        // -> http://example.org/bar/foo.xml?hello=world
-    .hash("hackernews")
-        // -> http://example.org/bar/foo.xml?hello=world#hackernews
-    .fragment("")
-        // -> http://example.org/bar/foo.xml?hello=world
-    .search("") // alias of .query()
-        // -> http://example.org/bar/foo.xml
-    .tld("com")
-        // -> http://example.com/bar/foo.xml
-    .search({ foo: "bar", hello: ["world", "mars"] });
-        // -> http://example.com/bar/foo.xml?foo=bar&hello=world&hello=mars

- -

How do you like working query strings?

URI("?hello=world")
-    .addSearch("hello", "mars")
-        // -> ?hello=world&hello=mars
-    .addSearch({ foo: ["bar", "baz"] })
-        // -> ?hello=world&hello=mars&foo=bar&foo=baz
-    .removeSearch("hello", "mars")
-        // -> ?hello=world&foo=bar&foo=baz
-    .removeSearch("foo")
-        // -> ?hello=world
-

- -

How do you like relative paths?

URI("/relative/path")
-    .relativeTo("/relative/sub/foo/sub/file")
-        // -> ../../../path 
-    .absoluteTo("/relative/sub/foo/sub/file");
-        // -> /relative/path

- -

How do you like cleaning things up?

URI("?&foo=bar&&foo=bar&foo=baz&")
-    .normalizeSearch();
-        // -> ?foo=bar&foo=baz
-
-URI("/hello/foo/woo/.././../world.html")
-    .normalizePathname();
-        // -> /hello/world.html

- -

How do you like detecting URIs within random text?

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) {
-    return "<a>" + url + "</a>";
-});
-
-/* result is:
-Hello <a>www.example.com</a>,
-<a>http://google.com</a> is a search engine, like <a>http://www.bing.com</a>
-<a>http://exämple.org/foo.html?baz=la#bumm</a> is an IDN URL,
-<a>http://123.123.123.123/foo.html</a> is IPv4 and <a>http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/foobar.html</a> is IPv6.
-links can also be in parens (<a>http://example.org</a>) or quotes »<a>http://example.org</a>«.
-*/
-

- -

How do you like comparing URLs?

var a = "http://example.org/foo/bar.html"
-        + "?foo=bar&hello=world&hello=mars#fragment",
-    b = "http://exAMPle.org:80/foo/../foo/bar.html"
-        + "?hello=mars&foo=bar&hello=world&#fragment";
-
-a !== b;
-URI(a).equals(b) === true;

- -

How do you like fiddling with the fragment?

// storing values in the fragment (hash):
-var uri = URI("#hello-world");
-uri.fragment({foo: "bar", bar: ["hello", "world"]});
-uri.fragment() === "foo=bar&bar=hello&bar=world";
-// required src/URI.fragmentQuery.js to be loaded
-
-// storing URLs in the fragment (hash):
-var uri = URI("http://example.org/#!/foo/bar/baz.html"),
-    furi = uri.fragment(true);
-furi.pathname() === "/foo/bar/baz.html";
-furi.pathname("/hello.html");
-uri.toString() === "http://example.org/#!/hello.html"
-// required src/URI.fragmentURI.js to be loaded

- -

How do you like parsing URNs?

var uri = URI("urn:uuid:c5542ab6-3d96-403e-8e6b-b8bb52f48d9a?query=string");
-uri.protocol() == "urn";
-uri.path() == "uuid:c5542ab6-3d96-403e-8e6b-b8bb52f48d9a";
-uri.query() == "query=string";

- -

How do you like URI Templating?

URI.expand("/foo/{dir}/{file}", {
-  dir: "bar",
-  file: "world.html"
-});
-// -> /foo/bar/world.html

- -

Authors

Rodney Rehm

- -

License

URI.js is published under the MIT license.

- -