Assert for TorqueScript

Download Code File

This resource will add assert, assertfatal and assertwarning functionality to TorqueScript.

AssertFatal, AssertWarning and AssertISV have existing in TGE for quite sometime, however TorqueScript does not have the same mechanisms for catching erroneous variables - which is where this resource comes in.

It is always good practice to ensure the input and output variables in methods are what you expect them to be. It serves as a good documentation technique (explicitly showing those variables which are mandatory), and also allows bugs be caught early.

This aim of this resource is to create an assertion system which can be used during development, and be left in production code without a dramatic impact on system performance. To that end, when the assertions are disabled, the function calls will simply return true in all situations (the only overhead is calling a function that immediately returns true).

Disabling of the script assertions is done through the definition, SCRIPT_ASSERTION_ENABLE, which is defined at the top of the changed console.h.

This resource has been tested in TGE 1.5.2, but should work in all versions (including TGEA) due to changes only being within the common console functionality.



--------------------------------------------------
Function Signatures and Example Usage
--------------------------------------------------
This resource will create three new TorqueScript functions: assert, assertfatal and assertwarning.
Using the assert functions are similar to those implemented in the C++ macros. Each function accepts two parameters - first being the boolean comparison, second being a (optional) message to display together with the relative error.
Each function will return the evaluation result, so the assert* calls can be made within 'if' logic.


assert - assert(expression, [optional] message)
Tests if expression == true.
Displays error message in console and function immediately stops executing on failure (returns).

Usage Example:
Check that the %this variable equals the %obj variable, if not, abort processing the current function:

assert(%this == %obj);

-------------------------

assertwarning - assertwarning(expression, [optional] message)
Tests if expression == true.
Displays warning message in console and function keeps executing on failure.

Usage Example:
Check that the %returnCode value is greater than 0, if not just show a warning message:

assertwarning(%returnCode > 0, "The return code wasn't greater than 0!");

-------------------------

assertfatal - assertfatal(expression, [optional] message)
Tests if expression == true.
Displays error message in console, popup box with fatal error and game exits.

Usage Example:
Check that the %client variable is set, otherwise a display a fatal error and exit the game:

assertfatal(isObject(%client));

--------------------------------------------------
Installation
--------------------------------------------------

Step 1: Download the file attached to this resource, scriptAssert.zip
* extract the contents out to the engine\console directory


Step 2: Add scriptAssert.cc to your project, in the engine\console folder filter
* For VisualStudio this is done by right-clicking on the console folder in the TorqueDemo project, Add-->Existing Item.., and selecting the scriptAssert.cc file.
* This file contains the ConsoleFunction definitions. If you want to change the displayed messages, this is the file to change them in.


Step 3: Merge the contents of the other included files:
* console.h
* console.cc
* compiledEval.cc
* consoleInternal.h
* consoleInternal.cc

The changes are made from stock TGE 1.5.2, so should be ok to just replace them, but you should learn to merge files anyway! Many tools are around, such as the free WinMerge.

The changes are clearly surrounded by:

//--------------------------------------------------
// Script Assert >>
//--------------------------------------------------
...
//--------------------------------------------------
// Script Assert <<
//--------------------------------------------------

Step 4: All the code changes are now done! Save the project, Clean Solution and Build.

Please post any bugs or questions!