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()

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.

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()

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)

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.

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.

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)

::: INTERNAL FUNCTION ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Support function used by DBG.DumpTable() to print sorted tables.

INPUT

• tbl : Tabel to sort
• outfunc : Output function

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.

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")

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.

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)

PRIVATE FUNCTION

TEST_ConsoleOutput()

Tests the debug to the console functionalities.
Also shows how to setup and use more channels to track functions.

TEST_DumpTable()

Simple program to test the DBG.DumpTable() function

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()

Little test to check if output is logged even if no channels are specified.