Line Logger Example

This is an example of collecting (accumulating) lines of text from a State or Value.

See the published documentation for a properly formatted version of this README.

When the state/value changes, the new text is sent to this script. It stores the last few lines and sends them back as a new State. The number of stored lines can be specified as a parameter to the append() function.

This particular example is tailored to collecting script errors from this plugin itself. It could be used as in the included Touch Portal button.

As described in Status and Logging, every time an unhandled script error is detected the plugin updates the Last script instance error State with the error message. A Touch Portal event handler detects the change and sends that line of text to this script. The script optionally also color-codes some parts of the error message; the error number, time stamp, and instance name.

Note

Assets for this example, including the code and sample button shown below, can be found in the project's repository at
https://github.com/mpaperno/DSEP4TP/tree/main/resources/examples/LineLogger/

// This script stores and returns N last lines of text in a FIFO buffer style,
// discarding older lines as new ones come in.  Lines are added via the append() method.
//
// This particular implementation can also color-code an incoming script error log
// from the DSEP "Last script instance error" state.
 
// text lines storage
var log_data = log_data || [];
 
// regex for splitting up log lines for colorizing the different parts;
// captures error number, time stamp, instance name, and (optionally) error type.
// Anatomy & example of an error message:
// ID   TIMESTAMP     STATE NAME  ERROR TYPE     ... rest of the error.
// 015 [04:12:29.817] DSE_TestTwo ReferenceError: while evaluating 'run()' and script 'test_script.js' at line 33: FileHandl is not defined
const logLineRx = new RegExp(/^(\d+) \[([\d:\.]+)\] ([^\s]+) ([^\s]+:)?/, "g");
 
// Call this function from the TP action's expression with the line to append, the number of lines to keep,
// and whether to try to color-code parts of the log entry.
export function append(line, maxLines = 6, colorize = false)
{
  // optionally wrap special TP color code commands around the error number, time stamp, instance name and error type parts of the new line.
  if (colorize)
    line = line.replace(logLineRx, "[c#EB6A6A]$1[/c] [[c#1697E8]$2[/c]] [c#E8CC16]$3[/c] [c#CF62CF]$4[/c]");
  // clear out old data if needed
  if (log_data.length >= maxLines)
    log_data.splice(0, log_data.length - maxLines + 1);
  // add the new line
  log_data.push(line);
  // join the stored lines array and return it; this will get sent back to TP as a state update for this instance's state name.
  return log_data.join('\n');
}
 
// Convenience function to clear the saved lines. Optional message to return as TP state value.
export function clear(returnString = "Script Log Cleared!") {
  log_data = [];
  if (typeof returnString !== 'undefined')
    return returnString;
}

Example usage on a button