Arrays

There's no direct support of arrays in the TPR scripting language. Arrays can be created only indirectly using indexed (numbered) variables. Referencing of values at a certain index can be then achieved with nested (recursive) variable calls.

This technique is already employed throughout the scripting language and you will spot it in many command examples:

  • Image comparison methods such as Image Search produce several arrays containing the X and Y coordinates of the matching locations on the screen.
  • Optical Character Recognition (OCR) represented by the Text OCR module parses the text recognized on the screen into an array of lines.
  • The Mail command returns multiple arrays with attributes of retrieved emails.
  • The String command allows you to parse a text and produces an array of elements.

See the Examples section of these commands specifications for code samples.


Variable Nesting

Let's explain variable call nesting on an example. You have two variables:

Var A3=100
Var INDEX=3

You may then retrieve value of the A3 variable as follows:

Var VALUE="{A{INDEX}}"

The language interpret processes the command as follows:

  1. It replaces the innermost variable call of "{INDEX}" with 3. This produces a new command like:
       Var VALUE="{A3}"
  2. The above command is then resolved as a standard A3 variable reference and the VALUE variable is populated with 100.


Creating Arrays

Let's create an array of three integers from 1 to 3 with the variable base name of "INT". This can be achieved by populating each variable separately:

Var INT1=1
Var INT2=2
Var INT3=3

You may also create the array using a "for" loop:

for (i=1; {i}<=3; i={i}+1) {
    Varg "set" name="INT{i}" value="{i}" scope=script
}


Use of the Varg command is necessary here. The Var command by default creates local variables which exist only within the block they are created in. "Varg" with the scope set to "script" will make sure that the variables will survive the loop block and stay visible in the whole script.


Iterating over Array Values

Iterating over array values is similar to the loop example above. If you know the array length you may for example print out the values as follows:

for (i=1; {i}<=3; i={i}+1) {
    Var V="{INT{i}}"
    Log "Value at index {i} is {V}"
}


If you do not know the array length you may modify the loop to iterate as long as the numbered variable exists:

Var n=1
for ( ; exists INT{n}; ) {
    Var V="{INT{n}}"
    Log "Value at index {n} is {V}"
    Eval n={n}+1
}


To set value of array values use nested variables again. For example, let's increment each array value:

for (i=1; {i}<=3; i={i}+1) {
    Eval INT{i}="{INT{i}}+1"
}



Deleting Arrays

There's no single command to delete the whole array in one go. You have to iterate over the variables and delete each one individually:

for (i=1; {i}<=3; i={i}+1) {
    Varg "delete" name="INT{i}"
}



Examples

Here's an example of how to list files in a local Mac OS X or Unix/Linux folder and print them out:

# Execute "ls" to list files in a folder
Exec "ls /Users"

# Split the Exec command output to lines using a regular expression
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

# Print out the first file in the directory
Var FILE1= "{_STRING1}"
Log "The very first file is {FILE1}"

# List other files
Log "Other files:"
for (i=2; i<={_STRING_COUNT}; i=i+1) {
    Log "File #{i} is: {_STRING{i}}"
}