The VAR_LOOP_START command begins a loop of commands over a range of numeric values or through a sequence of characters. This can be used as a simple counter or for more powerful things like custom gridding using coordinate values and naming exported files using the coordinates. Note that it is possible to nest loops and use different variable names for each loop to build complex filenames.
For any commands found within a VAR_LOOP_START...VAR_LOOP_END pair defining a loop, the current value of the loop variable will be available as a variable name. By default this will be %COUNTER%, but you can use the VAR_NAME parameter (see below) to make it whatever name that you want. By default some generic numeric formatting will be provided (i.e. whole numbers won't have a decimal or any leading 0's), but you can also provide custom formatting for the numeric value as a C-style format string like you would pass to a print command using the VAL_FORMAT parameter (see below for details).
The following parameters are used by the VAR_LOOP_START command.
- VAR_NAME - specifies the name of the variable that will be used to store the current loop value. By default this will be %COUNTER%, but you can use anything you want. See the example below for usage.
- VAL_START - specifies the value to start the loop out. This would be something like 1 for just a simple counter loop, but can be any number, or a single letter, like A.
- VAL_STOP - specifies the value to stop the loop out. When the current loop value goes past this value the loop will stop, but it will run at this value. So to do a loop from 1 to 10, including 10, use VAL_START=1, VAL_STOP=10, and VAL_STEP=1. To loop through the letters A through J, use VAL_START=A, VAL_STOP=J, and VAL_STEP=1.
- VAL_STEP - specifies the value to increment the loop variable by each time the commands are run through. If you don't provide this it will increment by 1 if the VAL_STOP is greater than VAL_START and -1 if they are reversed.
- VAL_FORMAT - specifies a C-style print format string for formatting the numeric loop variable as a string. For example to format as a 3-digit number with 0's filling in for values less than 100, use VAL_FORMAT="%03d". If you provide a custom format, it should always include exactly one % and end with a 'd' (for integer values) or a 'f' (for floating point). If you don't provide a format string a good default numeric representation will be used.
-
VALUE_TABLE - specifies the name of a previously defined table of values from a DEFINE_VAR_TABLE command to loop over a list of values from. If the table contains multiple columns of data, use VALUE_COLUMN to specify the name of the column of data to use for this variable if you just want to loop over a single column.
If you would like to access any column of the table from within the loop, use a variable name of the format %VAR_NAME:COLUMN_NAME% within the loop.
For example, if you use VAR_NAME="settings" and your VALUE_TABLE has columns named "height" and "width", you can use %settings:height% to access the height column from the current row of the settings table.
-
VALUE_COLUMN - specifies the name of a the column from the VALUE_TABLE to loop over. Only required for tables with multiple columns of data.
VAR_LOOP_END
The VAR_LOOP_END command ends a loop of commands over a range of numeric values. See the VAR_LOOP_START command for details.
SAMPLE
Here is a simple example for looping over some rows and columns:
GLOBAL_MAPPER_SCRIPT VERSION=1.00 // Loop over rows 1-10 with leading zeroes in the format VAR_LOOP_START VAL_START=1 VAL_STOP=10 VAL_STEP=1 VAL_FORMAT="%02d" VAR_NAME="%ROW%" // Loop over colums 5-15 in this row, use default formatting VAR_LOOP_START VAL_START=5 VAL_STOP=15 VAL_STEP=1 VAR_NAME="%COL%" // Import a file with the row and column in the filename IMPORT FILENAME="c:\path_to_file\base_filename_%ROW%_%COL%.jpg" VAR_LOOP_END VAR_LOOP_END