Section Assertions

Assertion functions, that extend Lua assert(...) standard function.

Assertions protect your code. Here is an unprotected code:

function Foo(str)
	return strlower(str)
end

Here you assume that str is a string, but what happen if str is a table, a Symbol?

Here is the protected version in Lua standard:

function Foo(str)
	assert(type(str) == "string", "Function Foo: str argument #1: string expected, got "..type(str))
	-- ... assert str is not empty
	assert(str ~= "", "... must not be empty")
	-- ... assert str contains a "W", why not?
	assert(strfind(str, "W", 1, true), "... must contains a 'W'")
	return strlower(str)
end

And now here is my recommanded code, that prints a stack strace to help you locate where the error happened:

function Foo(str)
	local stackName = "Foo(" .. tostring(str) .. ")"
	SMStack(stackName)
	assertNotEmptyString(str, "Foo, 'str' argument #1")
	assertExpression(strfind(str, "W", 1, true), "Foo, 'str' argument #1: must contain a 'W'")
	SMUnstack(stackName)
	return strlower(str)
end

Summary

Return type	Function and summary
boolean	assertBoolean(b, string errorMessage, boolean visual) Assert `b` is a boolean (`true` or `false`, not `nil`), else throw `errorMessage`.
boolean	assertDialog(dialog, string errorMessage, boolean visual) Assert `dialog` is a Dialog, else throw `errorMessage`.
boolean	assertEquals(expr, expected, string Text, boolean visual) Assertion an expression or function call equals an expected result.
boolean	assertExpression(expr, string errorMessage, boolean visual) Assert an expression result is true.
boolean	assertFalse(b, string errorMessage, boolean visual) Assert `b` is `false`, else throw `errorMessage`.
boolean	assertFunction(f, string errorMessage, boolean visual) Assert `f` is a function, else throw `errorMessage`.
boolean	assertInArray(value, table t, string text, boolean visual) Assert a value is found in a table.
boolean	assertNegativeNumber(n, string errorMessage, boolean visual) Assert `n` is a negative number, else throw `errorMessage`.
boolean	assertNil(n, string errorMessage, boolean visual) Assert `n` is `nil`, else throw `errorMessage`.
boolean	assertNotEmptyString(s, string errorMessage, boolean visual) Assert `s` is a not-nil and not empty string, else throw `errorMessage`.
boolean	assertNotNil(n, string errorMessage, boolean visual) Assert `n` is not `nil`, else throw `errorMessage`.
boolean	assertNotZero(n, string errorMessage, boolean visual) Assert `n` is a number but not `0`, else throw `errorMessage`.
boolean	assertNumber(n, string errorMessage, boolean visual) Assert `n` is a not-nil number, else throw `errorMessage`.
boolean	assertPositiveNumber(n, string errorMessage, boolean visual) Assert `n` is a positive number, else throw `errorMessage`.
boolean	assertScore(s, string errorMessage, boolean visual) Assert `s` is a Score, else throw `errorMessage`.
boolean	assertString(s, string errorMessage, boolean visual) Assert `s` is a not-nil string (possibly empty), else throw `errorMessage`.
boolean	assertTable(t, string errorMessage, boolean visual) Assert `t` is a table, else throw `errorMessage`.
boolean	assertTrue(b, string errorMessage, boolean visual) Assert `b` is `true`, else throw `errorMessage`.
boolean	assertType(t, string expectedType, string errorMessage, boolean visual) Assert `type(t)` is a `expectedType`, else throw `errorMessage`.

Functions

assertNumber(n, string errorMessage, boolean visual)

Assert n is a not-nil number, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected number, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will stop with a console error message.
See: assertPositiveNumber; assertNegativeNumber; assertNotZero

assertPositiveNumber(n, string errorMessage, boolean visual)

Assert n is a positive number, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected positive number, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNumber; assertNegativeNumber; assertNotZero

assertNegativeNumber(n, string errorMessage, boolean visual)

Assert n is a negative number, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected negative number, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNumber; assertPositiveNumber; assertNotZero

assertNotZero(n, string errorMessage, boolean visual)

Assert n is a number but not 0, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected not-zero number, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNumber; assertPositiveNumber; assertNegativeNumber

assertString(s, string errorMessage, boolean visual)

Assert s is a not-nil string (possibly empty), else throw errorMessage.

Parameter	Type	Default	Description
s			s
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected string, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNotEmptyString

assertNotEmptyString(s, string errorMessage, boolean visual)

Assert s is a not-nil and not empty string, else throw errorMessage.

Parameter	Type	Default	Description
s			s
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected not-empty string, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertString

assertBoolean(b, string errorMessage, boolean visual)

Assert b is a boolean (true or false, not nil), else throw errorMessage.

Parameter	Type	Default	Description
b			b
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected boolean, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertTrue; assertFalse; assertExpression

assertTrue(b, string errorMessage, boolean visual)

Assert b is true, else throw errorMessage.

Parameter	Type	Default	Description
b			b
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected true, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertFalse; assertNotNil; assertExpression

assertFalse(b, string errorMessage, boolean visual)

Assert b is false, else throw errorMessage.

Note: if you check a expression, e.g. x < y, Lua returns nil if the comparaison fails, instead of false.

Parameter	Type	Default	Description
b			b
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected false, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertTrue; assertNil; assertExpression

assertTable(t, string errorMessage, boolean visual)

Assert t is a table, else throw errorMessage.

Parameter	Type	Default	Description
t			t
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected table, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertFunction(f, string errorMessage, boolean visual)

Assert f is a function, else throw errorMessage.

Parameter	Type	Default	Description
f			f
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected function, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertNil(n, string errorMessage, boolean visual)

Assert n is nil, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected nil, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNotNil; assertFalse; assertExpression

assertNotNil(n, string errorMessage, boolean visual)

Assert n is not nil, else throw errorMessage.

Parameter	Type	Default	Description
n			n
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected not nil, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertNil; assertTrue; assertExpression

assertExpression(expr, string errorMessage, boolean visual)

Assert an expression result is true.

This is the equivalent of Lua assert function with more logging.

Parameter	Type	Default	Description
expr			Result of an expression, e.g. `x < y`
errorMessage	string		Nothing is concatenated, the message must be full and self-explainatory.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
See: assertTrue; assertNotNil

assertEquals(expr, expected, string Text, boolean visual)

Assertion an expression or function call equals an expected result.

This is useful for unit tests.

Parameter	Type	Default	Description
expr			Result of an expression
expected			Expected result
Text	string		to print on console and throw if `expr ~= expected`
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
Error: If expr ~= expected

assertInArray(value, table t, string text, boolean visual)

Assert a value is found in a table.

Parameter	Type	Default	Description
value			number or string. `nil` always fails the assertion.
t	table		List of values in which `value` is searched for.
text	string		Text to print on console and throw if `expr ~= expected`
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.
Error: If value not found in t

assertDialog(dialog, string errorMessage, boolean visual)

Assert dialog is a Dialog, else throw errorMessage.

Parameter	Type	Default	Description
dialog			dialog
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected Dialog, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertScore(s, string errorMessage, boolean visual)

Assert s is a Score, else throw errorMessage.

Parameter	Type	Default	Description
s			s
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected Score, got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return: boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertType(t, string expectedType, string errorMessage, boolean visual)

Assert type(t) is a expectedType, else throw errorMessage.

Parameter	Type	Default	Description
t			t
expectedType	string		expectedType
errorMessage	string		Message to throw: by convention, the function where it happen, and the argument's or variable's name. `": expected 'expectedType', got ..."` will be concatenated.
visual	boolean	false	Visual alert. Does not stop the script with a console error message, returns `true` if assertion is correct, `nil` if it fails. Your script must handle the returned value to stop gracefully.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

Example


assertType(s, "Staff", "MyFunction, argument #1")
 --> if s is not a Staff, this print
 --> ERROR MyFunction, argument #1, expected Staff, got ...