Other Language Statements
Context: HL Kit … Kit Reference
The scripting language supports additional statements for special purposes that can be extremely useful.
Perform Statement
A large number of target references that apply changes to objects within scripts return a value that you can ignore. For example, the "assign" target reference that assigns a tag to an object always returns the value zero. Putting it to use will normally look like the following:
var result as number result = assign[group.tag]
Declaring a variable in which to place a return value that you don't care about is unnecessary nuisance. So the scripting language provides the "perform" statement. The perform statement tells the compiler to invoke the operation that follows the statement and simply throw away the value returned. The above example changes to the code below when the "perform" statement is employed.
perform assign[group.tag]
The net result is simpler, shorter, and clearer scripting code.
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.
Append Statement
The "append" statement is used exclusively with the Synthesize script. When generating dossier output, the volume of text can be quite long, in which case the traditional "@text" special symbol becomes impractical and inefficient. So the append statement is provided as a means to output a chunk of text to HL and then allow the author to stop worrying about it. Once text is output via the append statement, it will be part of the synthesized output, and it will appear in the sequence it is output.
The syntax for the append statement is simple, as it uses a single string. When an append statement is executed, the string you specify is evaluated and then output as part of the dossier. This means that three append statements in a row will procedure output that is the concatenated result of all three strings, as shown below.
append "line #1" & @newline append @boldon & "line #2" & @boldoff & @newline append "line #3" & @newline
The final output that results from the above three statements would look like the following when synthesized for HTML:
line #1<br> <b>line #2</b><br> line #3<br>
Trustme Statement
As a general rule, scripts should not be directly modifying the contents of "user" fields. Those fields are intended for access only by the user, so attempts to modify them via scripts are inherently considered an error by the compiler. However, as with any rule, there are always the exceptions.
When a script needs to modify the value of a user field, the "trustme" statement can be used. This tells the compiler that you know what you're doing and can be trusted to not do things inappropriately. Once specified within a script, the script becomes trusted and the compiler stops checking for code that modifies user fields.
The syntax of the trustme statement is trivial. Simply place the statement on its own line within the script. There are no parameters, so it looks like below.
trustme
IMPORTANT! Whenever you think that you need to utilize the trustme statement, look closely at your script and what you're trying to do. It is rare that you should actually need to use trustme, and your data files probably can be better structured to eliminate the need for directly modifying a user field.
IMPORTANT! The following script types are automatically designated as "trusted". This is because their general nature is such that you'll often be needing to modify user fields.
