URL Parser

I know there are a few different examples of these out in the wild but none I could find were as simple as this.

Initialise a new url parser object

Initialise a new url parser object.

var simple = new URI("http://www.example.com");
var simpler = new URI(); // Use current location
var simplest = URI();

.getParts ()

This method does not accept any parameters Returns an array containing all URI components.

example = URI("http://username:[email protected]:8080/path/to/file/index.html?query=foo#bar");
result = example.getParts();
// Results =
{
directory: "/path/to/file/",
filename: "index.html",
fragment: "bar",
hostname: "www.example.com",
password: "password",
path: "/path/to/file/index.html",
port: "8080",
protocol: "http",
queryString: "query=foo",
suffix: "html",
userinfo: "username:password",
username: "username"
}

.protocol ([protocol])

Set or retrieve the url protocol.

example = new URI("http://www.example.com");
example.protocol(); // Returns "http"
example.protocol("https"); // Sets protocol, new url https://www.example.com

.userinfo ([userinfo])

Set or retrieve the user info

example = new URI("http://username:[email protected]/");
example.userinfo(); // Returns "username:password"
example.userinfo("admin:123456"); // Set userinfo, new url http://admin:[email protected]/

.username ([username])

Set or retrieve the username

example = new URI("http://username:[email protected]/");
example.username(); // Returns "username"
example.username("admin"); // Set username, new url http://admin:[email protected]/

.password ([password])

Set or retrieve the password

example = new URI("http://username:[email protected]/");
example.password(); // Returns "password"
example.password("123456"); // Set password, new url http://username:[email protected]/

.hostname ([hostname])

Set or retrieve the hostname

example = new URI("http://www.example.com/");
example.hostname(); // Returns "www.example.com"
example.hostname("example.com"); // Set hostname, new url http://example.com/

.port ([port])

Set or retrieve the port

example = new URI("http://www.example.com:8080/");
example.port(); // Returns "8080"
example.port(4545); // Set hostname, new url http://www.example.com:4545/

.path ([path])

Set or retrieve the path

example = new URI("http://www.example.com/path/to/page.html");
example.path(); // http://www.example.com/path/to/page.html
example.path("/new/path/to/page.html"); // Set hostname, new url http://www.example.com/new/path/to/page.html

.directory ([directory])

Set or retrieve the directory

example = URI("http://example.com/path/to/page.html");
example.directory(); // Returns "/path/to/"
example.directory("/new/path/"); // Set directory, new url http://example.com/new/path/page.html

.cd (directory)

Change the directory terminal style. Rather than replace the directory this function will allow you to manipulate the directory wih a familiar syntax

example = URI("http://example.com/one/two/three/four/five/index.html");
example.cd("../../new"); // Change directory, new url http://example.com/one/two/three/new/index.html
example.cd("./new/"); // Change directory, new url http://example.com/one/two/three/new/new/index.html 

.filename ([filename])

Set or retrieve the filename

example = URI("http://example.com/path/to/page.html");
example.filename(); // Returns "page.html"
example.filename("page2.html"); // Set filename, new url http://example.com/new/path/page2.html

.suffix ([suffix])

Set or retrieve the file suffix

example = URI("http://example.com/path/to/page.html");
example.suffix(); // Returns "html"
example.suffix("php"); // Set suffix, new url http://example.com/new/path/page.php

.queryString ([queryString])

Set or retrieve the queryString

example = URI("http://example.com?query=1");
example.queryString(); // Returns "query=1"
example.queryString("query=2"); // Set queryString, new url http://example.com?query=2

The following are alternative methods for working with the queryString as an object

.query ([queryObject])

Set or retrieve the query string as an object

example = URI("http://example.com?query=1");
example.query(); // Returns {query: 1}
example.query({query2: 2, query3: 3}); // Set query, new url http://example.com?query2=2&query3=3
example.query("query2"); // Retrieve value of "query2", Returns "2"

.addQuery (queryObject)

Add one or more items to the query string

example = URI("http://example.com?query=1");
example.addQuery({query2: 2, query3: 3}); // Add 2 items to the query string, new url http://example.com?query=1&query2=2&query3=3
example.addQuery({query3: 0}); // Will replace query3, new url http://example.com?query=1&query2=2&query3=0

.removeQuery (name,[index])

Remove a specific item from the query

example = URI("http://example.com?query=1&array[]=1&array[]=2");
example.removeQuery("query"); // Remove "query", new url http://example.com?array[]=1&array[]=2
example.removeQuery("array", 1); // Remove the 2nd index of "array", new url http://example.com?array=1

.fragment ([fragment])

Set or retrieve the fragment

example = URI("http://example.com/#anchor");
example.fragment(); // Returns "anchor"
example.fragment("newanchor"); // Set fragment, new url http://example.com/#newanchor

.isAbsolute ([url])

Returns true if the url is absolute

example = URI("http://example.com");
example.isAbsolute(); // Returns true
example.isAbsolute("/relative/url/index.html"); // Returns false

.isEqual (url,[strict],[includeQuery])

_Accepts a string or URI object, strict & includeQuery are both flags_

Returns true if both urls resolve to the same location.

example = URI("http://example.com/path/to/file/index.html");
example2 = URI("http://example.com/path/to/file/index.html");
// Basic usage will allow comparison between an absolute and relative urls
example.isEqual("/path/to/file/index.html"); // Returns true
example.isEqual("http://example.com/redundant/../path/to/file/index.html"); // Returns true, same location
example.isEqual(example2); // Returns true
// Strict comparison will only all absolute with absolute and relative with relative comparison
example.isEqual("/path/to/file/index.html", true); // Returns false
example.isEqual("http://example.com/path/to/file/index.html", true); Returns true
example.isEqual("http://example.com/redundant/../path/to/file/index.html"); // Returns true, same location
// includeQuery will factor the query string into the comparison
example = URI("http://example.com/path/to/file/index.html?query=1&query2=2");
example.isEqual("/path/to/file/index.html", false, true); // Returns false
example.isEqual("/path/to/file/index.html?query2=2&query=1", false, true); // Returns true, query order doesn"t matter

.isRelative ([url])

Returns true if the url is relative

example = URI("http://example.com");
example2 = URI("/relative/url/index.html");
example.isRelative(); // Returns false
example.isRelative("http://example.com"); // Returns false
example.isRelative("/relative/url/index.html"); // Returns true
example.isRelative(example2); // Returns true

.isURL (url)

Returns true if the url is valid

example = URI();
example.isURL("http://---------"); // Returns false
example.isURL("http://example.com"); // Returns true

.normalizePath (path)

Normalise a url or path string

example = URI();
example.normalizePath("http://example.com/redundant/../path/./index.html"); // Returns "http:/example.com/path/index.html"
example.normalizePath("/redundant/../path/./"); // Returns "/path/"

.setBase ([base])

Make a url relative to a new base.

example = URI("http://example.com/path/to/file/index.html");
example2 = URI("https://github.com/");
example.setBase(); // Set the base to the current window location
example.setBase("http://username:[email protected]:8080/path/is/irrelevant"); // Set base, new url http://username:[email protected]:8080/path/to/file/index.html
example.setBase(example2); // Set base, new url https://github.com/path/to/file/index.html
example.setBase(""); // Set base, new url /path/to/file/index.html 

.computed ()

_This method does not accept any parameters_

Returns the full encoded url

example = URI("http://example.com/one/two/../../index.html?query=abc");
example.computed(); // Returns http://example.com/index.html?query=abc
example.filename("home.html").queryString("");
example.computed(); // Returns http://example.com/home.html 

.src ([reset])

Returns the origional source string that the URI object was set with. This will not change unless the object is redefined or reset by passing this method a new string.

example = URI("http://example.com/one/two/../../index.html?query=abc");
example.computed(); // Returns http://example.com/index.html?query=abc
example.filename("home.html").queryString("");
example.computed(); // Returns http://example.com/home.html
example.src(); // Remains unchanged, returns "http://example.com/one/two/../../index.html?query=abc"