Debug Output Via Scripts

[Context: HL Kit … Basic Concepts and Terminology … Debugging Mechanisms]

Overview

In most traditional programming languages, there is the age-old technique of inserting a "print" statement at various points in the code to display the state information. This technique is used to verify that everything is behaving correctly and to diagnose errors that surface. The Kit provides two related mechanisms that offer a similar solution.

The "notify" Statement

The first mechanism is the "notify" statement within the scripting language. This statement allows you to synthesize a string and then display it to the user. The string can be anything, such as the contents of fields, the results of an arithmetic expression, or even just a simple error message. So you can display whatever information you need to convey.

The notify mechanism displays an alert message to the user, requiring the user to dismiss the message before continuing. It works very similarly to the way run-time errors are handled. Consequently, the notify mechanism is ideal for reporting unexpected and/or error conditions that are encountered during evaluation. It is also useful for inserting a quick verification of a few values during testing of new functionality.

The "debug" Statement

The second mechanism is the "debug" statement within the scripting language. Like the notify mechanism, this statement allows you to synthesize a string for output, but the resulting text is not displayed directly to the user. Instead, the text is sent to the Debug Output window, which can be shown via the "Floating Info Windows" sub-menu of the "Debug" menu.

When the Debug Output window is visible, the use of a sequence of "debug" statements will send a progressive series of messages to the window. You can use this technique to monitor the flow of execution through all of your scripts and watch both the values of fields and the presence of tags at various points during the evaluation cycle. Every time the evaluation cycle is triggered, all of the debug messages are output again, so you can easily watch the effects of changing selections and values within the character through each new evaluation cycle.

This particular technique is probably the single most valuable method for quickly diagnosing where things are going wrong within your scripts. Once you know where things are going wrong, it's usually pretty easy to figure out why the error is occurring and put in the proper correction.