Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

Link a questa pagina di confronto

hollywoodlibs:debug:functions [2017/07/16 11:12] (versione attuale)
admin creata
Linea 1: Linea 1:
 +====== 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​ChName</​color>​ : Add and enable the given channel to the output stream
 +  * <color #​008800>​ChColor</​color>​ : Optional channel color (ANSI CODE/​SEQUENCE),​ default Yellow+Bold
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the channel was added without errors
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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")
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + 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.
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the debug was disabled without errors.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​timing</​color>​ : Set this switch to TRUE to add a timestamp at the beggining of each data row.
 +  * <color #​008800>​ansi</​color>​ : TRUE to enable ANSI support (default)
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the debug was enabled without errors.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​message</​color>​ : Message to log, can be a STRING, NUMBER, NIL, TABLE.
 +  * <color #​008800>​Mode</​color>​ :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.
 +  * <color #​008800>​channel</​color>​ : Is the channel name where this message should be logged Defaults to '​standard'​.
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the message was logged without errors.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + ​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>​.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​ChName</​color>​ : Remove the given channel from the output stream
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the channel was removed without errors
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; Remove a defined debug channel so that the debug output for this
 +   ; channel will be stopped.
 +   ​DBG.Console.RemoveChannel("​MAIN PRG")
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + 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).
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​value</​color>​ : TRUE to enable all level-normal messages
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the action was successfull
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; Switch off all normal-level messages
 +   ​DBG.Console.Out.SkipNormalLevel(True)
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + ​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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​tbl</​color>​ : Tabel to sort
 +  * <color #​008800>​outfunc</​color>​ : 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​table</​color>​ : Table to dump
 +  * <color #​008800>​mode</​color>​ : 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>​.
 +  * <color #​008800>​sorted</​color>​ : Set to TRUE if you want the func output sorted
 +  * <color #​008800>​ident</​color>​ : [PRIVATE] Starting identation level
 +  * <color #​008800>​check</​color>​ : [PRIVATE] Used to recognize the first call from the recursive calls.
 +  * <color #​008800>​channel</​color>​ : Channel name where to output the table content, valid only for the console debug channels.
 +  * <color #​008800>​ccheck</​color>​ : [PRIVATE] check for circular recursion detection
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the table was dumped correctly
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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)
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​Channel</​color>​ : Channel to disable (optional)
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the debug was disabled without errors.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​LogFile</​color>​ : The file name where to write the log messages
 +  * <color #​008800>​Preserve</​color>​ : 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.
 +  * <color #​008800>​Timings</​color>​ : TRUE to log the messages timestamp.
 +  * <color #​008800>​ChannelName</​color>​ : Specify the channel name (optional, default = "​standard"​)
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the logging have been enabled correctly.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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"​)
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + 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.
 +
 +<color #​000000>​__INPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​Message</​color>​ : 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.
 +  * <color #​008800>​Mode</​color>​ : 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.
 +  * <color #​008800>​Channel</​color>​ : Where the log must be written.
 +
 +<color #​000000>​__OUTPUT__</​color>​\\ ​
 +
 +  * <color #​008800>​result</​color>​ : TRUE if the message was logged without errors.
 +
 +<color #​000000>​__EXAMPLE__</​color>​\\ ​
 +
 +   ; 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
 +
 +<color #​000000>​__NOTES__</​color>​\\ ​
 + ​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.\\ ​
 +
 +
  
hollywoodlibs/debug/functions.txt ยท Ultima modifica: 2017/07/16 11:12 da admin
CC Attribution-Noncommercial 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0