﻿# Mojo

## Namespace Detail

This section contains some methods that can be used to debug your applications and other utility functions (assert, require, loadScriptWithCallback...)

## Method Summary

- Mojo.assert(expression, message, messageProperties)
- Mojo.assertArray(expectedArray, message, messageProperties)
- Mojo.assertClass(object, constructorFunction, message, messageProperties)
- Mojo.assertDefined(value, message, messageProperties)
- Mojo.assertElement(expectedElement, message, messageProperties)
- Mojo.assertEqual(expected, actual, message, messageProperties)
- Mojo.assertFalse(expression, message, messageProperties)
- Mojo.assertFunction(expectedFunction, message, messageProperties)
- Mojo.assertMatch(regex, testValue, message, messageProperties)
- Mojo.assertNumber(expectedNumber, message, messageProperties)
- Mojo.assertProperty(properties)
- Mojo.assertString(expectedString, message, messageProperties)
- Mojo.doNothing()
- Mojo.loadScriptWithCallback(path, callback, optionalDocument)
- Mojo.parseJSON(jsonText)
- Mojo.require(expression, message, messageProperties)
- Mojo.requireArray(expectedArray, message, messageProperties)
- Mojo.requireClass(object, constructorFunction, message, messageProperties)
- Mojo.requireDefined(value, message, messageProperties)
- Mojo.requireElement(expectedElement, message, messageProperties)
- Mojo.requireEqual(expected, actual, message, messageProperties)
- Mojo.requireFalse(expression, message, messageProperties)
- Mojo.requireFunction(expectedFunction, message, messageProperties)
- Mojo.requireMatch(regex, testValue, message, messageProperties)
- Mojo.requireNumber(expectedNumber, message, messageProperties)
- Mojo.requireProperty(properties)
- Mojo.requireString(expectedString, message, messageProperties)

## Method Detail

### {String} Mojo.assert(expression, message, messageProperties)

Writes an error to the log if expression doesn't evaluate to boolean true.

The Mojo.require or Mojo.assert methods will do the same, except that require will throw an exception when their requirements aren't met. These are intended to be used in cases where framework code or application cannot reasonably continue if the requirements aren't met.

Example:

>     Mojo.assert(dogs > 3,
>       "expected dogs to be greater than #{count}, but it was #{amount}",
>       {count: 3, amount: dogs})

#### Parameters

- {Boolean} expression - expression that must evaluate to true
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

{String} the message that was written to the log.

### {string} Mojo.assertArray(expectedArray, message, messageProperties)

Writes an error to the log if expectedArray fails the Prototype isArray method.

#### Parameters

- {Boolean} expectedArray - object that must be an array
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertClass(object, constructorFunction, message, messageProperties)

Writes an error to the log if targetObject wasn't constructed by the passed-in constructor function.

#### Parameters

- {Object} object - object to check for constructing function.
- {Function} constructorFunction - expected constructor function.
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertDefined(value, message, messageProperties)

Writes an error to the log if value evaluates to undefined.

#### Parameters

- {Boolean} value - value that must not evaluate to undefined
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertElement(expectedElement, message, messageProperties)

Writes an error to the log if expectedElement fails the Prototype isElement method.

#### Parameters

- {Boolean} expectedElement - object that must be an element
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertEqual(expected, actual, message, messageProperties)

Writes an error to the log if expected === actual is not true.

#### Parameters

- {anything} expected - expected value
- {anything} actual - actual value
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertFalse(expression, message, messageProperties)

Writes an error to the log if expression evaluates to boolean true.

#### Parameters

- {Boolean} expression - expression that must evaluate to false
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertFunction(expectedFunction, message, messageProperties)

Writes an error to the log if expectedFunction fails the Prototype isFunction method.

#### Parameters

- {Boolean} expectedFunction - object that must be a function
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertMatch(regex, testValue, message, messageProperties)

Writes an error to the log if the regex doesn't match the testValue.

#### Parameters

- {Regex} regex - regex to match
- {String} testValue - string to attempt to match against the regex.
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.assertNumber(expectedNumber, message, messageProperties)

Writes an error to the log if expectedNumber fails the Prototype isNumber method.

#### Parameters

- {Boolean} expectedNumber - object that must be a number
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### Mojo.assertProperty(properties)

Writes an error to the log if targetObject doesn't have values for the property name or names passed in.

#### Parameters

- {String||Array} properties - individual name or array of names of properties to check

### {string} Mojo.assertString(expectedString, message, messageProperties)

Writes an error to the log if expectedString fails the Prototype isString method.

#### Parameters

- {Boolean} expectedString - object that must be a string
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### Mojo.doNothing()

A simple empty function useful as a stub.

### Mojo.loadScriptWithCallback(path, callback, optionalDocument)

Asynchronously load a JavaScript file by adding a script tag to the header of the document.

#### Parameters

- {String} path - Path to the source file. If relative it is relative to the document.
- {Function} callback - Function that is called when the script either completes loading or fails to load.
- {HTMLDocument} optionalDocument - Document to which to add the script tag. Defaults to the global document.

### Mojo.parseJSON(jsonText)

Parses a text string of encoded in JSON, returning a JavaScript object (result) when successful.

#### Parameters

- {String} jsonText - input string with encoded JSON

### {String} Mojo.require(expression, message, messageProperties)

Writes an error to the log if expression doesn't evaluate to boolean true.

The Mojo.require and Mojo.assert methods will do the same thing, except that Mojo.require will throw an exception when its requirements aren't met. The Mojo.requireXxxx methods are intended to be used in cases where framework code or application cannot reasonably continue if the requirements aren't met.

Example:

>     Mojo.require(dogs > 3,
>       "expected dogs to be greater than #{count}, but it was #{amount}",
>       {count: 3, amount: dogs})

#### Parameters

- {Boolean} expression - expression that must evaluate to true
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

{String} the message that was written to the log.

### {string} Mojo.requireArray(expectedArray, message, messageProperties)

Writes an error to the log if expectedArray fails the Prototype isArray method and throws an exception.

#### Parameters

- {Boolean} expectedArray - object that must be an array
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireClass(object, constructorFunction, message, messageProperties)

Writes an error to the log if targetObject wasn't constructed by the passed in constructor function and throws an exception.

#### Parameters

- {Object} object - object to check for constructing function.
- {Function} constructorFunction - expected constructor function.
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireDefined(value, message, messageProperties)

Writes an error to the log if value evaluates to undefined and throws an exception.

#### Parameters

- {Boolean} value - value that must not evaluate to undefined
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireElement(expectedElement, message, messageProperties)

Writes an error to the log if expectedElement fails the Prototype isElement method and throws an exception.

#### Parameters

- {Boolean} expectedElement - object that must be an element
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireEqual(expected, actual, message, messageProperties)

Writes an error to the log if expected === actual is not true and throws an exception.

#### Parameters

- {anything} expected - expected value
- {anything} actual - actual value
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireFalse(expression, message, messageProperties)

Writes an error to the log if expression evaluates to boolean true and throws an exception.

#### Parameters

- {Boolean} expression - expression that must evaluate to false
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log

### {string} Mojo.requireFunction(expectedFunction, message, messageProperties)

Writes an error to the log if expectedFunction fails the Prototype isFunction method and throws an exception.

#### Parameters

- {Boolean} expectedFunction - object that must be a function
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireMatch(regex, testValue, message, messageProperties)

Writes an error to the log if the regex doesn't match the testValue and throws an exception.

#### Parameters

- {Regex} regex - regex to match
- {String} testValue - string to attempt to match against the regex.
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### {string} Mojo.requireNumber(expectedNumber, message, messageProperties)

Writes an error to the log if expectedNumber fails the Prototype isNumber method and throws an exception.

#### Parameters

- {Boolean} expectedNumber - object that must be a number
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.

### Mojo.requireProperty(properties)

Writes an error to the log if targetObject doesn't have values for the property name or names passed in and throws an exception.

#### Parameters

- {String||Array} properties - individual name or array of names of properties to check

### {string} Mojo.requireString(expectedString, message, messageProperties)

Writes an error to the log if expectedString fails the Prototype isString method and throws an exception.

#### Parameters

- {Boolean} expectedString - object that must be a string
- {String} message - a custom message to use if the assertion fails. This message will be run through template evaluation against the messageProperies object, so you can include details of the assertion failure in the message.
- {Object} messageProperties - object containing values to use with template evaluation.

#### Returns

The message that was written to the log.