BuildForge Help

.drill

.drill [through] <"var1,var2,var3"|$EnvVar|-r[p] Register> [gr[ouped by] "{}"] [sep[arated by] ","] [exec] "Command $1 $2"

The .drill command allows you to loop over a command, executing the command once for each member of a series of values. You can specify the values on the command line, or draw them from an environment variable or register. When it executes a .drill command, the system uses the .drill syntax to construct a series of command lines and sends them to the agent for execution.

For example, the command .drill "A,B,C,D" "echo value $1" creates the following commands:
echo value A 
echo value B 
echo value C 
echo value D

Grouping

You can group the values and reference multiple values in each group using the $1, $2, etc. syntax. $1 refers to the first value in the group, $2 to the second value in the group. For example, .drill through "(A,B,C,D,E),(B,C,D,E,F),(C,D,E,F,G)" grouped by "()" separated by "," exec "echo 1[$1] 2[$2] 3[$3] 4[$4] 5[$5]" creates these commands:
echo 1[A] 2[B] 3[C] 4[D] 5[E] 
echo 1[B] 2[C] 3[D] 4[E] 5[F] 
echo 1[C] 2[D] 3[E] 4[F] 5[G]
Note: There is no default grouping character. There is a default separator character, the comma. If you do not specify grouped by, the system looks through the supplied values as separated by the separator character and considers each such string a single value. For example, the command .drill "(A,B),(C,D)" "echo $1 $2" resolves to the following commands:
echo (A 2 
echo B) 2
echo (C 2
echo D) 2

Data Sources

You have several options for where the .drill command gets the data that it loops through. The first parameter for the command is the data source. You can include the optional command word "through" to indicate the data source.
  • You can explicitly list the data in the command line, as in the following command, which loops over the values one, two, and three:
    .drill through "one,two,three" exec "echo $1"
  • You can draw the data from an environment variable. The following command assumes that the environment variable FILENAMES is a comma-separated list of files, and uses a DOS command to delete all the files in the list:
    .drill through $FILENAMES exec "del $1"
  • You can draw the data from a register or a project register. If RegisterA contains a comma-separated list of filenames, then the following command issued to a Linux system writes out the content of each file:
    .drill -r RegisterA exec "cat $1"
    while the following example does the same but uses a project register:
    .drill -rp ProjectRegisterA exec "cat $1" 
Related concepts
Registers