Uri

Module	ejs
Definition	class Uri
Inheritance	Uri Object
Specified	ejscript-2.5
Stability	Evolving.

The URI class to provides the ability to create, and manipulate URIs and their constituent components.

Uri objects are mutable.

Properties

Qualifiers	Property	Type	Description
get	address	String	Return the TCP/IP address of the URI. This is the IP:PORT portion.
get	basename	Uri	The base of portion of the URI. The base portion is the trailing portion of the path without any directory elements. Set to null if the Uri has no path.
get	components	Object	Break a URI into its components by converting the URI to an absolute URI and breaking into components. The components are: scheme, host, port, path, reference and query.
get	dirname	Uri	The directory portion of a URI path. The directory portion is the leading portion including all directory elements of the URI path excluding the base name. Set to null if the Uri has no path.
get set	extension	String	The URI extension portion of the path. Set to a String containing the URI extension without the ".". Set to null if no extension. If this is modified, the path property will be updated accordingly.
get	filename	Path	Set to a Path type corresponding to the Uri path property. The Path is relative to the current directory. i.e. this removes the leading "/" from the path property. (.
get	hasExtension	Boolean	Does the URI has an explicit extension 8.
get	hasHost	Boolean	Does the URI have an explicit host component. For example: "www.example.com".
get	hasPort	Boolean	Does the URI have an explicit port number.
get	hasQuery	Boolean	Does the URI have an explicit query component.
get	hasReference	Boolean	Does the URI have an explicit reference component.
get	hasScheme	Boolean	Does the URI have an explicit scheme (protocol) specifier. For example: "http://".
get set	host	String	The host portion of the URI. Set to null if there is no host component.
get	isAbsolute	Boolean	Is the URI is an absolute path. Set to true if the URI path component beginning with a "/".
get	isDir	Boolean	Is the URI is a directory URI. Set to true if the URI ends with "/". NOTE: this only tests the URI and not any physical resource associated with the URI. 0.
get	isRegular	Boolean	Is the URI is a regular resource and not a directory. Set to true if the URI does not end with "/". NOTE: this only tests the URI and not any physical resource associated with the URI.
get	isRelative	Boolean	Is if the URI path is relative. Set to true if the URI's path component does not begin with a "/".
get	local	Uri	Create a local URI. A local URI has no scheme, host or port components.
get	mimeType	String	The mime type of the URI. This is set to a mime type string by examining the URI extension. Set to "text/html" if the mime type cannot be determined from the extension. Set to null if the URI has no extension.
get	normalize	Uri	Normalized URI by removing all redundant and invalid URI components. Set to a URI with "segment/.." and "./" components removed. The value will not be converted to an absolute URI nor will it map character case.
get set	path	String	The URI path portion after the hostname Set to null if there is no path.
get set	port	Number	The port number of the URI. Set to null if the URI does not have an explicit port.
get set	query	String	The URI query string. The query string is the fragment after a "?" character in the URI. Set to null if there is no query. 0.
get set	reference	String	The URI reference portion. The reference portion is sometimes called the "anchor" and is the the fragment after a "#" character in the URI. Set to null if there is no reference.
get set	scheme	String	The URI protocol scheme. Set to null if no scheme defined.
get set	uri	String	The full URI as a string.

Inherited Properties

Uri Class Methods

Qualifiers	Method
static	decode(str: String): String
	Decode a URI encoded string using www-url encoding.
static	decodeComponent(str: String): String
	Decode a URI encoded component using www-url encoding.
static	encode(str: String): String
	Encode a URI using www-url encoding.
static	encodeComponent(str: String): String
	Encode a URI component suitable for the "application/x-www-form-urlencoded" mime type.
static	template(pattern: String, options: Array): Uri
	Create a URI based on a template.

Inherited Methods

Uri Instance Methods

Qualifiers	Method
	Uri(uri: Object)
	Create and parse a Uri object.
	absolute(base = null): Uri
	Create a complete absolute URI from "this" URI with all mandatory components present including scheme and host.
	complete(missing = null): Uri
	Create a complete absolute URI from "this" URI with all mandatory components present including scheme and host.
	endsWith(suffix: Object): Boolean
	Return true if the URI path ends with the given suffix.
	join(others: Array): Uri
	Join URIs.
	joinExt(ext: String): Uri
	Join an extension to a URI.
	relative(base): Uri
	Create a URI with a relative path from the base URI to "this" URI.
	replaceExt(ext: String): Uri
	Replace the extension and return a new URI.
	resolve(target): Uri
	Resolve a URI in the neighborhood of this URI.
	same(other: Object, exact: Boolean = false): Boolean
	Compare two URIs test if they represent the same resource.
	startsWith(prefix: Object): Boolean
	Return true if the URI path starts with the given prefix.
override	toJSON(): String
	Convert the URI to a JSON string.
override	toLocalString(): String
	Convert the local portion of the URI to a string.
override	toString(): String
	Convert the URI to a string.
	trimEnd(pat: String): Uri
	Trim a pattern from the end of the URI path NOTE: this does a case-sensitive match.
	trimExt(): Uri
	Trim the extension portion off the URI path.
	trimStart(pat: String): Uri
	Trim a pattern from the start of the path NOTE: this does a case-sensitive match.

Inherited Methods

Method Detail

Uri(uri: Object)

Description: Create and parse a Uri object.

Parameters

uri: Object

A string or object hash that describes the URI. The uri specify a complete absolute URI string or it may specify a partial URI where missing elements take the normal defaults. The uri argument may also be an object hash with the following properties.

Options

scheme	String URI protocol scheme (http or https).
host	String URI host name or IP address.
port	Number TCP/IP port number for communications.
path	String URI path.
query	String URI query parameters. Does not include "?".
reference	String URI path reference. Does not include "#".

absolute(base = null): Uri

Description: Create a complete absolute URI from "this" URI with all mandatory components present including scheme and host. The resulting URI path will be normalized and any missing components will be completed with values from the given base URI. If "this" URI path is relative, it will be joined to base URI's path. Any query component of "this" URI is discarded in the result. This is because the query component of "this" URI is regarded as POST data and not integral to the base URI.

Parameters

base	Optional URI to provide missing components and a base URI path if the current URI path is relative. The base argument can be a string, URI or an object hash of URI component. If the base argument is not supplied, the current URI will be completed as much as possible. See complete. [default: null]

Returns: A complete, absolute URI.

static decode(str: String): String

Description: Decode a URI encoded string using www-url encoding. See encode for details about the character mappings.

Parameters

str: String

String to decode.

Returns: A decoded string.

static decodeComponent(str: String): String

Description: Decode a URI encoded component using www-url encoding. See encodeComponent for details about the character mappings.

Parameters

str: String

String to decode.

Returns: A decoded string.

complete(missing = null): Uri

Description: Create a complete absolute URI from "this" URI with all mandatory components present including scheme and host. The resulting URI path will be normalized and missing (mandatory) components will be completed with values from the given "missing" argument.

Parameters

missing

Optional URI to provide the missing components. The missing argument can be a string, URI or an object hash of URI component. If this missing argument is not provided, the following defaults are used: "http://localhost:80/". [default: null]

Returns: A complete, absolute URI.

static encode(str: String): String

Description: Encode a URI using www-url encoding. This replaces special characters with encoded alternative sequence. The encode call replaces all characters except: alphabetic, decimal digits, "-", "_", ".", "!", "~", "*"", "'", "(", ")", "#", ";", ",", "/", "?", ":", ".

Parameters

str: String

String to encode.

Returns: An encoded string.

static encodeComponent(str: String): String

Description: Encode a URI component suitable for the "application/x-www-form-urlencoded" mime type. This replaces special characters with encoded alternative sequence. The encode call replaces all characters except: alphabetic, decimal digits, "-", "_", ".", "!", "~", "*"", "'", "(", ")". It also maps space to "+". Compared with the encode call, encodeComponent additionally encodes: "#", ";", ",", "/", "?", ":", ".

Parameters

str: String

String to encode.

Returns: An encoded string.

endsWith(suffix: Object): Boolean

Description: Return true if the URI path ends with the given suffix.

Parameters

suffix: Object

URI or String suffix to compare with the path.

Returns: True if the path does begin with the suffix.

join(others: Array): Uri

Description: Join URIs. URI argument are joined in turn starting with "this" URI" as the base. If a URI argument is absolute, the progressive result is replaced with the absolute URI and joining continues. If a URI argument is relative, a "/" is appended followed by the argument, and joining continues. For example: Uri("/admin").join("/display") will result in "/display" Uri("/admin").join("logout") will result in "/admin/logout" Uri("/admin").join("private", "profile") will result in "/admin/private/profile".

Parameters

others: Array

Other URIs to join. These can be URIs, strings or object hashes of URI components.

Returns: A new URI with the arguments joined to the current URI.

joinExt(ext: String): Uri

Description: Join an extension to a URI. If the basename of the URI already has an extension, this call does nothing.

Returns: A URI with an extension.

relative(base): Uri

Description: Create a URI with a relative path from the base URI to "this" URI. If the base URI has a different scheme, host or port to that of "this" URI, then a relative URI cannot be formed and the current URI is returned. Any query component of the base URI is ignored in the result. This is because the query component is regarded as POST data and not integral to the base URI.

Parameters

base	Base URI to use in calculating the relative path to "this" URI. The base argument can be a string, URI or an object hash of URI component.

Returns: A new URI object with a relative path from the base URI to "this" URI.

replaceExt(ext: String): Uri

Description: Replace the extension and return a new URI.

Returns: A path with extension. 8.

resolve(target): Uri

Description: Resolve a URI in the neighborhood of this URI. Resolve operates like join, except that it joins the given URI to the directory portion of the current ("this") URI. For example:

Uri("/a/b.html").resolve("c.html") will return "/a/c.html".

Resolve operates by determining a virtual current directory for this URI (dirname). It then joins the given URI path to the directory portion of the current result. If the resolving URI is an absolute URI, it is used unmodified.

Resolve is useful for creating URIs in the region of the current URI and gracefully handles both absolute and relative URI segments. Any query component of "this" URI is discarded in the result. This is because the query component of "this" URI is regarded as POST data and not integral to the base URI.

Parameters

target

Other URI to resolve in the region of this path. Target can be a URI, string or object hash of URI components.

Returns: A new URI object that resolves given URI args using the "this" URI as a base.

same(other: Object, exact: Boolean = false): Boolean

Description: Compare two URIs test if they represent the same resource.

Parameters

other: Object	Other URI to compare with.
exact: Boolean	If exact is true, then the query and reference portions must match. [default: false]

Returns: True if the URIs represent the same underlying resource.

startsWith(prefix: Object): Boolean

Description: Return true if the URI path starts with the given prefix. This skips the scheme, host and port portions and examines the URI path only.

Parameters

prefix: Object

URI or String prefix to compare with the URI.

Returns: True if the path does begin with the prefix.

static template(pattern: String, options: Array): Uri

Description: Create a URI based on a template. The template is a subset of the URI-templates specification and supports simple {tokens} only. Each token is looked for in the set of provided option objects. The search stops with the first object providing a value.

Parameters

pattern: String	URI-Template with {word} tokens.
options: Array	Set of option objects with token properties to complete the URI.

Returns: A URI.

override toJSON(): String

Description: Convert the URI to a JSON string.

Returns: A JSON string representing the URI.

override toLocalString(): String

Description: Convert the local portion of the URI to a string. This will include only the path, query and reference components of the URI. The scheme, host and port portions of the URI will be ignored.

Returns: A string representing the URI's path, query and reference portions.

override toString(): String

Description: Convert the URI to a string.

Returns: A string representing the URI.

trimEnd(pat: String): Uri

Description: Trim a pattern from the end of the URI path NOTE: this does a case-sensitive match. TODO - is this right?.

Returns: A new URI containing the trimmed URI TODO - should support reg expressions.

trimExt(): Uri

Description: Trim the extension portion off the URI path.

Returns: A URI with no extension.

trimStart(pat: String): Uri

Description: Trim a pattern from the start of the path NOTE: this does a case-sensitive match. TODO - is this right?.

Returns: A URI containing the trimmed path name TODO - should support reg expressions.