log

Oct 31, 2021

Library "log"
Logging library for easily displaying debug, info, warn, error and critical messages.

No real need to explain why you might want to use this library! I'm sure you've all experienced the frustration of trying to understand the data state of your scripts... so, enjoy! More on it's way...

(Don't forget to check the helpers in the script and the useful tips below)

Some Useful Tips

By default the log console persists between bars (for history) and bars and ticks (for realtime).
Sometimes it is useful to clear the log after each candle or tick (assuming we are using the above helpers):

```
log_print(clear = true) // starts afresh on every bar and tick (excludes historical bars but good realtime tick analysis)
log_print(clear = barstate.isnew) // clears the log at the start of each bar (again, excludes historical but good realtime candle analysis)
```

It is also useful to be able to selectively understand the state of data at specific points or times within a script:

```
if log.once()
debug('useful variable', my_var) // this log only gets written once, upon first execution of this statement

if log.only(5)
debug3(a, b, c) // these variables are only logged the first five times this statement is executed

log_print(clear = false) // clear must be false and you should not write other logs on every bar, or the above will be lost
```

Final tip. If you want to view ONLY log entries of a particular level, then negate the constant:

```
log_print(level = -LOG_DEBUG)
```

Detailed Interface

once() Restrict execution to only happen once. Usage: if assert.once()\n happens_once()
  Returns: bool, true on first execution within scope, false subsequently

only(repeat) Restrict execution to happen a set number of times. Usage: if assert.only(5)\n happens_five_times()
  Parameters:
    repeat: int, the number of times to return true
  Returns: bool, true for the set number of times within scope, false subsequently

init() Initialises the log array
  Returns: string[], tuple based array to contain all pending log entries (__LOG)

clear(msgs) Clears the log array
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)

trace(msgs, msg) Writes a trace message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the trace message to write to the log

debug(msgs, msg) Writes a debug message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the debug message to write to the log

info(msgs, msg) Writes an info message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the info message to write to the log

warn(msgs, msg) Writes a warning message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the warn message to write to the log

error(msgs, msg) Writes an error message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the error message to write to the log

fatal(msgs, msg) Writes a critical message to the log console
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    msg: string, the fatal message to write to the log

log(msgs, level, msg) Write a log message to the log console with a custom level
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    level: ing, the logging level to assign to the message
    msg: string, the log message to write to the log

severity(msgs) Checks the unprocessed log messages and returns the highest present level
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
  Returns: int, the highest level found within the unfiltered logs

print(msgs, level, clear, rows, text_size, position) Prints all log messages to the screen
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    level: int, the minimum required log level of each message to be displayed
    clear: bool, clear the printed log console after each render (useful with realtime when set to barstate.isconfirmed)
    rows: int, the number of rows to display in the log console
    text_size: string, the text size of the log console (global size vars)
    position: string, the position of the log console (global position vars)

unittest_log(case) Log module unit tests, for inclusion in parent script test suite. Usage: log.unittest_log(__ASSERTS)
  Parameters:
    case: string[], the current test case and array of previous unit tests (__ASSERTS)

unittest(verbose) Run the log module unit tests as a stand alone. Usage: log.unittest()
  Parameters:
    verbose: bool, optionally disable the full report to only display failures

Nov 1, 2021

Release Notes

v2 - Added disabling of automatic line numbers. Fixed mistakes in helpers.

Updated:
print(msgs, level, clear, rows, text_size, position, line_numbers) Prints all log messages to the screen
  Parameters:
    msgs: string[], the current collection of unfiltered and unprocessed logs (__LOG)
    level: int, the minimum required log level of each message to be displayed
    clear: bool, clear the printed log console after each render (useful with realtime when set to barstate.isconfirmed)
    rows: int, the number of rows to display in the log console
    text_size: string, the text size of the log console (global size vars)
    position: string, the position of the log console (global position vars)
    line_numbers: bool, disable the automatic prepending of line numbers

Apr 7, 2022

Release Notes

v3 - Updated inaccurate comments.