Other Language Statements

Context: HL Kit … Kit Reference 

The scripting language supports additional statements for special purposes that can be extremely useful.

Foreach Statement

There will be times when you need to iterate through a collection of objects, separately processing each individual object within the collection. For example, you might want to iterate through all the weapons possessed by the character to determine how many "hands" worth of weapons are equipped by the character.

In situations like this, the "foreach" statement provides the perfect solution. The foreach statement requires that you specify something to iterate over. The loop is terminated by the "nexteach" statement, resulting in the code within the foreach/nexteach block being invoked for every instance that satisfies the foreach criteria.

Only a single form of "foreach" statement is currently supported, and it iterates through the picks that have been added to a container, processing only those that satisfy a specified set of criteria. This is accomplished by specifying a container to be processed and a tag expression that identifies the picks within the container to be processed. A loop is generated that iterates through each pick within the container that satisfies the tag expression, resulting in the code within the foreach/nexteach block being invoked for every pick in the container that satisfies the tag expression. Within the foreach/nexteach block, the current pick can be accessed via the "eachpick." script context. The net result is that a typical foreach/nexteach block looks like the code below.

foreach pick in hero where "group.tag"
    debug "id: " & eachpick.idstring
    nexteach

In the above code, the "foreach" statement stipulates what type of object is to be iterated ("pick"), followed by the "in" designation and a valid container script context ("hero"). The container context can be anything that is valid within the initial script context, so it can be "hero" or it could also be something like "child[pickid].gizmo". Once the container is given, the literal "where" must be given, followed by a string expression that is treated as a tag expression and evaluated when the "foreach" statement is evaluated.

The above code will iterate through all picks within the hero and identify all that possess the "group.tag" tag. The "debug" statement (see below) will then output the unique id of each of the picks that are processed by the "foreach" statement, since the "eachpick." script context specifies access to the current pick within the body of the loop.

Debug Statements

If you need to write more than a few, simple scripts, the odds are that something won't work at some point along the way. So Hero Lab includes some very helpful debugging aids. One of these aids is the "debug" statement. The debug statement allows you to have Hero Lab output any information you can access via scripts to the screen during the evaluation process. When a debug statement is executed, the string you specify is evaluated and then output to the special debug information window within HL, where you can view the results and determine what changes need to be made to your scripts. An example code block using the debug statement is provided below.

var foo as number
foo = 10
var bar as string
bar = "hello"
debug "foo = " & foo & " and bar = [" & bar & "]"

The final output from the above script code will be as shown below within the debug info window.

foo = 10 and bar = [hello]

Using the debug statement requires that you utilize the info windows within HL. To view the debug output, go to the "Debug" menu within HL, select the "Floating Info Windows" option, and then select the "Show Debug Output" sub-option. This will display a window which contains the debug information that has been output from your scripts.

As your scripts continue executing and the debug window fills up, the oldest information will be lost off the top to keep memory consumption to a minimum.

Notify Statement

In order to facilitate debugging and to provide a convenient means for data files to report special events to the user, the "notify" statement is provided. The notify statement works similarly to the "debug" statement, except that the resulting string is reported directly to the user via a message alert. For all practical purposes, the syntax for the "notify" statement is identical to the "debug" statement, except that the line starts with "notify", as shown below.

notify "This is the message displayed"

The notification is queued and then reported to the user at the first reasonable opportunity. This means that the message is not necessarily reported to the user immediately when it is triggered. Similarly, if there are multiple notification messages, they will be accumulated by HL and then reported collectively at the next opportunity. The messages will be displayed within a single report to the user, with each message on a separate line.