b9j.uri - URI (Uniform Resource Identifier) parsing, manipulation, and generation
var uri = new b9j.uri.URI( "http://example.com/a/b?a=1&b=2&c=3&c=4&c=5" )
var host = uri.host()
var uriChild = uri.child("c.html") // http://example.com/a/b/c.html?a=1&b=2& ...
uriChild.query.add({ c: [ 6, 7 ], d: 8 }) // ... ?a=1&b=2&c=3&c=4&c=5&c=6&c=7&d=8
uriChild.query.set("b", 9) // ... ?a=1&b=9&c ...
return uriChild.toString()
This package provides a way to parse, manipulate, and generate URIs. Specifically, it splits up a URI into three objects: the URI, the path, and the query. The path and query are subordinate, and changes to either object will be reflected in their "owner" URI.
It uses a modified parseUri (by Steven Levithan) for URI parsing: http://blog.stevenlevithan.com/archives/parseuri
Parse $uri (which should be a string) and return a hash containing the following:
scheme
authority
userInformation
user
password
host
port
relative
path
directory
file
query
queryHash
fragment
An example:
... = b9j.uri.parse("http://example.com:8080/?a=1&b=2")
See also RFC3986 (http://tools.ietf.org/html/rfc3986)
This method is adapted from parseUri 1.2 by Steven Levithan
Parse $query (which should be a string) and return a key/value hash:
var hash = b9j.uri.parseQuery("a=1&b=2")
// hash is { a: 1, b: 2 }
If the the query string contains a multi-value key, then that key is represented in the hash by an array instead of a simple value:
var hash = b9j.uri.parseQuery("a=1&b=2&c=4&c=5&c=6")
// hash is { a: 1, b: 2, c: [ 4, 5, 6 ] }
This function is an alias for b9j.uri.query.parse( ... )
Returns a new URI object representing the current value of window.location
Returns a new URI object representing $uri, which can either be a string or a hash resulting from b9j.uri.parse
Returns a clone of uri
Returns the scheme of uri, which is something like http, https, ftp, ...
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => http
Sets the scheme of uri to $scheme
Returns uri
An alias for uri.scheme() and uri.scheme( ... )
Returns the authority of uri, which is something like example.com:80 or user:password@www.example.net
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => alice:xyzzy@www.example.net
Sets the authority of uri to $authority
Returns uri
Returns the host of uri, which is something like example.com or www.example.net
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => www.example.net
Sets the host of uri to $host
Returns uri
Returns the port of uri, which can be empty (think default port) or something like 8080, 8000, ...
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => 8080
Sets the port of uri to $port
Returns uri
Returns the user of uri, if any
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => alice
Sets the user of uri to $user
Returns uri
Returns the password of uri, if any
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => xyzzy
Sets the password of uri to $password
Returns uri
Returns the userInformation of uri, if any. The user information is usually something like user:password
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => alice:xyzzy
Sets the userInformation of uri $userInformation, which will in turn update user, password, and authority appropiately
Returns uri
Returns the fragment of uri, if any
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => top
Sets the fragment of uri to $fragment
Returns uri
Returns the query of uri, which is a b9j.uri.query.Query object
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => a=1&b=2&c=3&c=4&c=5
You can make changes to the returned query object, and these will be reflected in uri
Sets the query of uri to $query, which can be either a string or a key/value hash. For example
// The following are equivalent
uri.query( "a=1&b=1&b=2" )
uri.query( { a: 1, b: [ 1, 2 ] } )
Returns uri
Returns the path of uri, which is a b9j.path.Path object
http://alice:xyzzy@www.example.net:8080/apple/banana/?a=1&b=2&c=3&c=4&c=5#top => /apple/banana/
You can make changes to the returned path object, and these will be reflected in uri
Sets the path of uri to $path, which can be either a string or an array of path parts
// The following are equivalent
uri.path( "a/b/c" )
uri.path( [ 'a', 'b', 'c' ] )
Returns uri
Modify uri by updating the path to the parent of the current path. For example:
var uri = new b9j.uri.URI("http://example.com/a/b/c")
uri.up()
uri.toString() // http://example.com/a/b
Modify uri by updating the path to the child of the current path by $path. For example:
var uri = new b9j.uri.URI("http://example.com/a/b/c")
uri.down( "c/d", "e/" )
uri.toString() // http://example.com/a/b/c/d/e/
Returns a clone of uri that is the parent (path-wise) of uri. For example:
var uri = new b9j.uri.URI("http://example.com/a/b/c")
var parent = uri.parent()
uri.toString() // http://example.com/a/b/c
parent.toString() // http://example.com/a/b
Returns a clone of uri that is the child (path-wise) of uri by $path. For example:
var uri = new b9j.uri.URI("http://example.com/a/b/c")
var child = uri.child( "c/d", "e" )
uri.toString() // http://example.com/a/b/c
child.toString() // http://example.com/a/b/c/d/e/
Modify uri by appending $part1 WITHOUT separating it by a slash. Any, optional, following $part2, ..., will be separated by slashes as normal
var uri = new b9j.uri.URI( "http://example.net/a/b/c" )
uri.append( "d", "ef/g", "h" ) // "http://example.net/a/b/cd/ef/g/h"
Returns the extension of uri, including the leading the dot
Returns "" if uri does not have an extension
new b9j.uri.URI( "http://example.net/a/b/c.html" ).extension() // .html
new b9j.uri.URI( "http://example.net/a/b/c" ).extension() // ""
new b9j.uri.URI( "http://example.net/a/b/c.tar.gz" ).extension() // .gz
new b9j.uri.URI( "http://example.net/a/b/c.tar.gz" ).extension({ match: "*" }) // .tar.gz
Modify uri by changing the existing extension of uri, if any, to $extension
new b9j.uri.URI( "http://example.net/a/b/c.html" ).extension( ".txt" ) // http://example.net/a/b/c.txt
new b9j.uri.URI( "http://example.net/a/b/c.html" ).extension( "zip" ) // http://example.net/a/b/c.zip
new b9j.uri.URI( "http://example.net/a/b/c.html" ).extension( "" ) // http://example.net/a/b/c
Returns uri
Set the uri to $uri, completely reinitializing the object (including path and query)
Merge $query with the current query of uri
$query can either be a query string or hash (simple object). An example:
var uri = new b9j.uri.URI("http://example.com/?a=1&b=2&c=3&c=4&c=5")
// The following are equivalent
uri.mergeQuery( "b=6&b=7&c=8&d=9" )
uri.mergeQuery( { b: [ 6, 7 ], c: 8, d: 9 }
// And will result in
uri.query.toString() // a=1&b=6&b=7&c=8&d=9
Returns uri in string-form
Parse $query (which should be a string) and return a key/value hash:
var hash = b9j.uri.parseQuery("a=1&b=2")
// hash is { a: 1, b: 2 }
If the the query string contains a multi-value key, then that key is represented in the hash by an array instead of a simple value:
var hash = b9j.uri.parseQuery("a=1&b=2&c=4&c=5&c=6")
// hash is { a: 1, b: 2, c: [ 4, 5, 6 ] }
Returns a new Query object representing $query, which can either be a (query) string or a hash resulting from b9j.uri.query.parse
Returns a clone of query
Returns the query store directly as a hash (simple object), so you can do the following:
var hash = new b9j.uri.query.Query("a=1&b=2")
if (query.get.a) { ...
Returns the value for $key If $key is multi-value, then return only the first value of $key
Returns an array containing every value for $key If $key is a single-value, then return an array with one element.
Set $key to $value in query $value can be a single value or an array
Set $key to an array of [ $value1, $value2, ... ]
Returns query
Set query uri to $uri, completely reinitializing the object
$query can be a query string or hash (simple object)
Returns query
Add $query to query, where $query can be a query string or hash (simple object)
Returns query
Add $value to $key
If $key does not exist, then $key is set to $value
If $key already has a value, multiple or otherwise, then $value is appended
Add $value1, $value2, ... to $key, turning it into a multi-value key
Returns query
Clear $key from query
Returns query
Clear every key/value from query, essentially turning it into the empty query
Returns query
Merge $query with the query
$query can either be a query string or hash (simple object). An example:
var query = new b9j.uri.query.Query("a=1&b=2&c=3&c=4&c=5")
// The following are equivalent
query.merge( "b=6&b=7&c=8&d=9" )
query.merge( { b: [ 6, 7 ], c: 8, d: 9 }
// And will result in
query.toString() // a=1&b=6&b=7&c=8&d=9
Returns query
Append $query_string to the output of query.toString()
This will NOT do any encoding on $queryString, nor can you otherwise manipulate the contests using query.set, etc.
Pass in null to erase the previous $querString
Returns query
Returns true if query is empty ("")
Returns query in string-form
b9j - A JavaScript toolkit
Robert Krimen <robertkrimen at gmail.com> http://bravo9.com
Available as part of b9j: b9j-latest.zip
You can contribute or fork this project via GitHub:
http://github.com/robertkrimen/b9j/tree/master
git clone git://github.com/robertkrimen/b9j.git
Copyright 2008 Robert Krimen
Code licensed under the BSD License: http://appengine.bravo9.com/b9j/documentation/license.txt