Indice
Debug Lib Functions
All Debug functions are mapped on the DBG table.
- DBG.Console.AddChannel(ChannelName, ChannelColor)
- DBG.Console.Disable()
- DBG.Console.Enable(timing, ansi)
- DBG.Console.Out(Message, Mode, Channel)
- DBG.Console.RemoveChannel(ChannelName)
- DBG.Console.SkipNormalLevel(value)
- DBG.DTS(tbl, outfunc)
- DBG.DumpTable(table, mode, sorted, ident, check, rec_count, channel, ccheck)
- DBG.Log.Disable(Channel)
- DBG.Log.Enable(LogFile, Preserve, Timings, ChannelName)
- DBG.Log.Out(Message, Mode, Channel)
- DebugPrint3(a, b, c)
- TEST_ConsoleOutput()
- TEST_DumpTable()
- TEST_LogOutput_2Channels()
- TEST_LogOutput_Anonym()
DBG.Console.AddChannel(ChannelName, ChannelColor)
result = DBG.Console.AddChannel(ChName, ChColor)
Defines and enable a new console debug channel named <ChName>.
The optional <ChColor> defines the color for ANSI capable consoles.
INPUT
- ChName : Add and enable the given channel to the output stream
- ChColor : Optional channel color (ANSI CODE/SEQUENCE), default Yellow+Bold
OUTPUT
- result : TRUE if the channel was added without errors
EXAMPLE
; The following code enables the debug output to the console, ; add a debug channel and output some debug text. DBG.Console.Enable(True, True) DBG.Console.AddChannel("MAIN PRG", Ansi.Code.FgYellow) DBG.Console.Out("This is just a test!", Nil, "MAIN PRG")
NOTES
The channel color is defined by an ANSI sequence you can input directly or using the inbuilt sequences defined in the Ansi Lib, like the above example.
Channel name is not case sensitive.
DBG.Console.Disable()
result = DBG.Console.Disable()
Disable the debug output to the console.
OUTPUT
- result : TRUE if the debug was disabled without errors.
EXAMPLE
; Disable the debug output for all messages DBG.Console.Disable()
DBG.Console.Enable(timing, ansi)
result = DBG.Console.Enable(timing)
Enable the debug output to the console. If <timing> is set to TRUE a timestamp will be added to the beggining of the data we are logging, defaults to FALSE.
INPUT
- timing : Set this switch to TRUE to add a timestamp at the beggining of each data row.
- ansi : TRUE to enable ANSI support (default)
OUTPUT
- result : TRUE if the debug was enabled without errors.
EXAMPLE
; Enable the timestamp and the ANSI colors DBG.Console.Enable(True, True)
DBG.Console.Out(Message, Mode, Channel)
result = DBG.Console.Out(Message, Mode, Channel)
If the console debug has been activated with <DBG.Console.Enable> and the channel has been added to the enabled channels list the <message> will be printed to the console.
INPUT
- message : Message to log, can be a STRING, NUMBER, NIL, TABLE.
- Mode :Can be one of the following:
- DBG.OpenFunc : Set the message as an open function message, must be paired with a DBG.CloseFunc message.
- DBG.CloseFunc : Set the message as a close function message, must be paired with a DBG.OpenFunc message for correct identation.
- DBG.Warning : Hilight the message as a warning message.
- DBG.Hilight : Hilight the message to make it more visibile.
- DBG.Error : Hilight the message as an error message.
- Nil : Do not specify anything to log a normal message.
- channel : Is the channel name where this message should be logged Defaults to 'standard'.
OUTPUT
- result : TRUE if the message was logged without errors.
EXAMPLE
; Brief example to print en error message DBG.Console.Out("ERROR! File not found!", DBG.Error, "myProg")
Here is another example that shows how to use messages whitin functions:
Function checkFile(filename) DBG.Console.Out("Calling checkFile()", DBG.OpenFunc, "myProg") If Exists(filename) DBG.Console.Out("File has been detected.", Nil, "myProg") Else DBG.Console.Out("File not found -> " .. filename, DBG.Warning, "myProg") EndIf DBG.Console.Out(Nil, DBG.CloseFunc, "myProg") EndFunction
NOTES
It's important to pair messages with mode DBG.OpenFunc and DBG.CloseFunc to mantain a correct identation.
DBG.Console.RemoveChannel(ChannelName)
result = DBG.Console.RemoveChannel(ChName)
Remove an existing console debug channel named <ChName>.
INPUT
- ChName : Remove the given channel from the output stream
OUTPUT
- result : TRUE if the channel was removed without errors
EXAMPLE
; Remove a defined debug channel so that the debug output for this ; channel will be stopped. DBG.Console.RemoveChannel("MAIN PRG")
NOTES
As soon as you have removed a channel all its subsequencing output requests will be discarded.
DBG.Console.SkipNormalLevel(value)
result = DBG.Console.SkipNormalLevel(value)
Switch On or Off the normal-level-messages logging. Set <value> to TRUE to skip normal-level-messages, otherwise set it to FALSE (default).
INPUT
- value : TRUE to enable all level-normal messages
OUTPUT
- result : TRUE if the action was successfull
EXAMPLE
; Switch off all normal-level messages DBG.Console.Out.SkipNormalLevel(True)
NOTES
Normal-level-messages are the messages without a message type specified, have alook at the DBG.Console.Out() function.
DBG.DTS(tbl, outfunc)
DBG.DTS(tbl, outfunc)
::: INTERNAL FUNCTION ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Support function used by DBG.DumpTable() to print sorted tables.
INPUT
- tbl : Tabel to sort
- outfunc : Output function
DBG.DumpTable(table, mode, sorted, ident, check, rec_count, channel, ccheck)
result = DBG.DumpTable(table, mode, sorted, ident, check, rec_count, channel, ccheck)
Dump the <table> contents according to the <mode> specified, <ident> is a private variable used in recursive dumping and should not be used directly.
INPUT
- table : Table to dump
- mode : Output mode to use, can be:
- DBG.OutMode_Straight : Dump directly to the console even if the debug is disabled.
- DBG.OutMode_Console : Dump to the console (if active)
- DBG.OutMode_Log : Dump to the log file (if active) Defaults to <DBG.OutMode_Straight>.
- sorted : Set to TRUE if you want the func output sorted
- ident : [PRIVATE] Starting identation level
- check : [PRIVATE] Used to recognize the first call from the recursive calls.
- channel : Channel name where to output the table content, valid only for the console debug channels.
- ccheck : [PRIVATE] check for circular recursion detection
OUTPUT
- result : TRUE if the table was dumped correctly
EXAMPLE
; Force the dump of a table to the console Local myTable = { a = 1, b = { 1, 2, 3 }, c = { name = "Joe", surname = "Meona" } } DBG.DumpTable(myTable, Nil, True)
NOTES
There are several interval variable to tune up this function (that is the same used in DBG.Log.Out and DBG.Console.Out when you specify a table as a message to log):
- DBG.DumpTableIdentSize = 3 ; Used to hilight nested tables by DumpTable
- DBG.DumpTableMaxRecursion = 8 ; Maximum recursion level
- DBG.DumpTableHideEmpty = False ; Hide empty tables
- DBG.DumpTableHideFunctions = False ; Hide functions
Sorting the output will mess up messages about maximum recursion level.
DBG.Log.Disable(Channel)
result = DBG.Log.Disable()
Disable the debug output to the file.
INPUT
- Channel : Channel to disable (optional)
OUTPUT
- result : TRUE if the debug was disabled without errors.
EXAMPLE
; Disable the debug output for all messages DBG.Log.Disable()
Or you can disable also a single channel if needed:
DBG.Log.Disable("myProg")
DBG.Log.Enable(LogFile, Preserve, Timings, ChannelName)
result = DBG.Log.Enable(LogFile, Preserve, Timings)
Enable the debug output messages to a log file named <LogFile>.
The channel will be attached to the given file name so that all subsequential messages will be putted on that log file.
INPUT
- LogFile : The file name where to write the log messages
- Preserve : TRUE to preserve the previous log file (if present), it will be renamed adding the .backup extention. If a file with the same name exists, it will be deleted.
- Timings : TRUE to log the messages timestamp.
- ChannelName : Specify the channel name (optional, default = “standard”)
OUTPUT
- result : TRUE if the logging have been enabled correctly.
EXAMPLE
; Enable the logging of all messages coming from the give channel to the ; specified log file. DBG.Log.Enable("log.txt", False, True, "myProg") DBG.Log.Out("Just a test!", DBG.Hilight, "myProg")
NOTES
You can easily redirect messages to several files to separate channels and have a better reading of the generated messages.
DBG.Log.Out(Message, Mode, Channel)
result = DBG.Log.Out(Message, Mode)
If the debug output has been activated with <DBG.Log.Enable> then the <message> will be written to the log file.
INPUT
- Message : The message to log, can be a STRING, NUMBER, NIL, TABLE.
The following special strings are also supported:- #SYSINFO# : Will log current system informations
- #COMMANDLINE# : Will log the command line used to execute the current program.
- Mode : Can be one of the following:
- DBG.OpenFunc : Set the message as an open function message, must be paired with a DBG.CloseFunc message.
- DBG.CloseFunc : Set the message as a close function message, must be paired with a DBG.OpenFunc message.
- DBG.Warning : Hilight the message as a warning message.
- DBG.Error : Hilight the message as an error message.
- Nil : Do not specify anything to log a normal message.
- Channel : Where the log must be written.
OUTPUT
- result : TRUE if the message was logged without errors.
EXAMPLE
; Brief example to print en error message DBG.Log.Out("ERROR! File not found!", DBG.Error, "myProg")
Here is another example that shows how to use messages whitin functions:
Function checkFile(filename) DBG.Log.Out("Calling checkFile()", DBG.OpenFunc, "myProg") If Exists(filename) DBG.Log.Out("File has been detected.", Nil, "myProg") Else DBG.Log.Out("File not found -> " .. filename, DBG.Warning, "myProg") EndIf DBG.Log.Out(Nil, DBG.CloseFunc, "myProg") EndFunction
NOTES
It's important to pair messages with mode DBG.OpenFunc and DBG.CloseFunc to mantain a correct identation.
DebugPrint3(a, b, c)
DebugPrint3(a, b, c)
PRIVATE FUNCTION
TEST_ConsoleOutput()
TEST_ConsoleOutput()
Tests the debug to the console functionalities.
Also shows how to setup and use more channels to track functions.
TEST_DumpTable()
TEST_DumpTable()
Simple program to test the DBG.DumpTable() function
TEST_LogOutput_2Channels()
TEST_LogOutput_2Channels()
Tests file log functionalities.
Also shows how to use 2 channels to split log messages in 2 log files.
TEST_LogOutput_Anonym()
TEST_LogOutput_Anonym()
Little test to check if output is logged even if no channels are specified.