Index Top Class Summary Constants Functions

Section Debug

Debugg and log functions.

If like me, you code in Notepad++ and don't use the debugger, or you intensively print(...) for debuging, here are some useful functions.

Log levels

There are 5 levels of loging, from trace to error:

trace(...) instead of print, for very low-level debuging,
debug(...) to write debuging messages on the Console when the script is run from the editor, in "debuging mode",
info(...) to write message on the console for all users.
It's recommand to use visual messages, SMMessage(...), but if your script already writes on the console, it's OK.
warn(...) writes a message on the console, to warn that something strange happened, but the script can still run.
Usage : you can warn in deprecated code, if something wrong happened and you ignore it but tell the user that he must fix the problem for better results.
It's recommanded to use SMAlert(...) instead.
err(...) writes an error message and stop the script.
This means there is a bug in the script and it must be fixed.

To force the log level of your script, for traces, just add

LOG_LEVEL = LOG_LEVEL_TRACE

just after Include "SMUtils".
If you want to write verbous log to a file, set

LOG_FILE = "C:/temp/mylog.txt"

. You can analyse the log file using Notepadd++ or another text editor.

throw(...) is the same than err(...) and prints the stack trace. All assertions functions wthro a message to protect the code.

Stack trace

To know the stack trace, your functions must call SMStack(...) and SMUnstack(...), see the example below:

function DoSomething(str)
	local stackName = "DoSomething(" .. tostring(str) .. ")"
	SMStack(stackName)
	-- assertions
	assertNotEmptyString(str, "DoSomething, 'str' argument #1")
	-- statments
	if str < "Hello" then
		str = strlower(str)
	end
	-- exit
	SMUnstack(stackName)
	return str
end

In case the argument is not a string, let's say a number, you'll have the error and the stack says

ERROR:
Stack: DoSomething, 'str' argument #1: expected not empty string, got number.
	DoSomething(3.14)

... and caller functions if they also have SMStack and SMUnstack calls.

Class

Class	Summary
Stopwatch	Stopwatch (French: chronomètre) to measure elapsed time.

Summary

Constant	Type	Summary
LOG_FILE	string	Output logs in a file?
LOG_LEVEL	int	Logging level for your script.
LOG_LEVEL_DEBUG	int	Logging level: debug
LOG_LEVEL_ERROR	int	Logging level: error
LOG_LEVEL_INFO	int	Logging level: info
LOG_LEVEL_TRACE	int	Logging level: trace, a more detailled debug
LOG_LEVEL_WARN	int	Logging level: warning

Return type	Function and summary
	SMProfilerStart() Start a profiler, to help you optimize your code.
Map	SMProfilerStop(boolean printStats) Stop the profiler, and prints the stats on the console.
	SMStack(string funcName) Add function name in the stack trace.
	SMUnstack(string funcName) Remove function name from the stack trace.
	debug(...) Log debugging informations.
	err(...) Log error This print `"ERROR "..text` to the console.
	info(...) Log informations.
	printStackTrace(int size) Prints the stack trace to the console
	tdebug(...) Return the structure of a table, Collection or Map for debugging to the console.
	throw(string exception, boolean visual, function catch) Log (console and/or file) and stop the script with `error()`.
	trace(...) Log trace-debugging informations.
	warn(...) Log warning This print `"WARN "..text` to the console.

Constants

string LOG_FILE

Output logs in a file?

Set LOG_FILE to a filename if you want so. Log lines older than 30 days are automatically deleted to avoid endless growth of the file.

int LOG_LEVEL_TRACE

Logging level: trace, a more detailled debug

int LOG_LEVEL

Logging level for your script.

By default, it's set to LOG_LEVEL_DEBUG if run from the script editor, in debug mode, and LOG_LEVEL_INFO if run from the menu.

Functions

throw(string exception, boolean visual, function catch)

Log (console and/or file) and stop the script with error().

Inspired from Java's throw new Exception(...) with a function as 'catch' mechanism.

Parameter	Type	Default	Description
exception	string		Error message
visual	boolean	false	Visual alert. If `true`, does not stop the script with a console error. Your script must handle this to stop gracefully.
catch	function	nil	If present, call this function. If `catch()` returns `true`, the script is stopped, else it continues at your own risks.

See: err

tdebug(...)

Return the structure of a table, Collection or Map for debugging to the console.

Parameter	Type	Default	Description
...			Structure(s) to debug

trace(...)

Log trace-debugging informations.

This allow you to keep logging in your script, even if shared with Myriad community.

This print "TRACE "..text to the console.
If you often use print and comment all these prints before sharing, this will save you time!

Parameter	Type	Default	Description
...			...

debug(...)

Log debugging informations.

This allow you to keep logging in your script, even if shared with Myriad community.

By default, debugs will appear on console when script is run in debug mode, and hidden if run directly from the menu.

This print "DEBUG "..text to the console.
If you often use print and comment all these prints before sharing, this will save you time!

Parameter	Type	Default	Description
...			...

info(...)

Log informations.

This print "INFO "..text to the console.

Parameter	Type	Default	Description
...			...

warn(...)

Log warning This print "WARN "..text to the console.

Parameter	Type	Default	Description
...			...

err(...)

Log error This print "ERROR "..text to the console.

Parameter	Type	Default	Description
...			...

See: throw

SMProfilerStart()

Start a profiler, to help you optimize your code.

This count functions calls and watch the spent time for each call.
The profiler also consume a bit of time and memory, so use it only when you are concerned by execution time of your script. Never publish a script with profiler enabled!
Once your code is optimized, remove the calls to SMProfilerStart and stop.

See: SMProfilerStop for printing results.

SMProfilerStop(boolean printStats)

Stop the profiler, and prints the stats on the console.

Parameter	Type	Default	Description
printStats	boolean	true

Return: Map: Map of function name (key), to table values. Structure of the table may varies, so it's highly recommand to let the printStats to it's default value.

SMStack(string funcName)

Add function name in the stack trace.

Stack trace is printed in the console in case of assertion fail or throw that stop the script.
Lua errors (syntax, divide by zero, out of memory) can't display the stack.
Don't forget to remove it before the return or end of the function using SMUnstack.

This function tries to alert (warning messag ein console) if stack overflow may occur shortly. If so, it prints the stack trace.

Parameter	Type	Default	Description
funcName	string		funcName

See: SMUnstack

SMUnstack(string funcName)

Remove function name from the stack trace.

Parameter	Type	Default	Description
funcName	string		funcName

See: SMStack

printStackTrace(int size)

Prints the stack trace to the console

Parameter	Type	Default	Description
size	int	15	Max number of lines to print

See: SMStack; SMUnstack