Documentation: Add Loop Templating Examples (#471)

Summary:
Pull Request resolved: #471

Adds two examples of using the Golang `text/template` functionality built into TTPForge to iterate over nested loops.

Reviewed By: cedowens

Differential Revision: D51838203

fbshipit-source-id: f351c2d78a0e0b64c11046f65eed896d374e82ec

example-ttps/templating/loops-integers.yaml

@@ -0,0 +1,41 @@
+---
+name: Creating Loops with Templating - Integers Example
+description: |
+  TTPForge's support for native Golang-style templates can
+  be used to create dynamic nested loops that execute a
+  step (or multiple steps) several times
+args:
+  - name: max_i
+    type: int
+  - name: max_j
+    type: int
+  - name: max_k
+    type: int
+tests:
+  - name: Loop Over Integer Ranges
+    args:
+      max_i: 2
+      max_j: 3
+      max_k: 4
+steps:
+  # we declare our loop limit variables here for two reasons:
+  # 1. We can shift to one-based indexing for our loops
+  # 2. Using (for example) ".Args.max_j" inside the loop over $i
+  #    is not possible due to template scoping rules
+  {{$lim_i := int (add .Args.max_i 1)}}
+  {{$lim_j := int (add .Args.max_j 1)}}
+  {{$lim_k := int (add .Args.max_k 1)}}
+  {{range $i := untilStep 1 $lim_i 1}}
+    {{range $j := untilStep 1 $lim_j 1}}
+      - name: outer_step_{{$i}}_{{$j}}
+        print_str: "Executing outer step with (i,j) = ({{$i}},{{$j}})"
+        # note that we need the indentation of the step in the inner
+        # loop to match the outer loop or our YAML will be invalid.
+        # Hence, the lines inside the $k loop are not indented as much
+        # as you might expect
+        {{range $k := untilStep 1 $lim_k 1}}
+      - name: inner_step_{{$i}}_{{$j}}_{{$k}}
+        print_str: "Executing inner step with (i,j,k) = ({{$i}},{{$j}},{{$k}})"
+        {{end}}
+    {{end}}
+  {{end}}

example-ttps/templating/loops-strings.yaml

@@ -0,0 +1,22 @@
+---
+name: Creating Loops with Templating - Strings Example
+description: |
+  This example demonstrates how to loop over specific
+  sets of string values during TTP execution.
+args:
+  - name: first_list
+  - name: second_list
+tests:
+  - name: Loop Over Lists of Letters
+    args:
+      first_list: "a,b,c"
+      second_list: "d,e,f"
+steps:
+  {{$first_args := splitList "," .Args.first_list}}
+  {{$second_args := splitList "," .Args.second_list}}
+  {{range $first_arg := $first_args}}
+    {{range $second_arg := $second_args}}
+      - name: print_combo_{{$first_arg}}_{{$second_arg}}
+        print_str: "Combination: ({{$first_arg}},{{$second_arg}})"
+    {{end}}
+  {{end}}

example-ttps/templating/loops.yaml

@@ -0,0 +1,38 @@
+---
+name: Creating Loops with Templating
+description: |
+  TTPForge's support for native Golang-style templates can
+  be used to create dynamic nested loops that execute a
+  step (or multiple steps) several times
+args:
+  - name: max_i
+    type: int
+    default: 2
+  - name: max_j
+    type: int
+    default: 3
+  - name: max_k
+    type: int
+    default: 4
+steps:
+  # we declare our loop limit variables here for two reasons:
+  # 1. We can shift to one-based indexing for our loops
+  # 2. Using (for example) ".Args.max_j" inside the loop over $i
+  #    is not possible due to template scoping rules
+  {{$lim_i := int (add .Args.max_i 1)}}
+  {{$lim_j := int (add .Args.max_j 1)}}
+  {{$lim_k := int (add .Args.max_k 1)}}
+  {{range $i := untilStep 1 $lim_i 1}}
+    {{range $j := untilStep 1 $lim_j 1}}
+      - name: outer_step_{{$i}}_{{$j}}
+        print_str: "Executing outer step with (i,j) = ({{$i}},{{$j}})"
+        # note that we need the indentation of the step in the inner
+        # loop to match the outer loop or our YAML will be invalid.
+        # Hence, the lines inside the $k loop are not indented as much
+        # as you might expect
+        {{range $k := untilStep 1 $lim_k 1}}
+      - name: inner_step_{{$i}}_{{$j}}_{{$k}}
+        print_str: "Executing inner step with (i,j,k) = ({{$i}},{{$j}},{{$k}})"
+        {{end}}
+    {{end}}
+  {{end}}