From 7634dc65879ec43a108a4b2d44d7eb2105a2a4b1 Mon Sep 17 00:00:00 2001 From: Samuel Manzer Date: Tue, 5 Dec 2023 08:30:14 -0800 Subject: [PATCH] Documentation: Add Loop Templating Examples (#471) Summary: Pull Request resolved: https://github.com/facebookincubator/TTPForge/pull/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 | 41 +++++++++++++++++++++ example-ttps/templating/loops-strings.yaml | 22 +++++++++++ example-ttps/templating/loops.yaml | 38 +++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 example-ttps/templating/loops-integers.yaml create mode 100644 example-ttps/templating/loops-strings.yaml create mode 100644 example-ttps/templating/loops.yaml diff --git a/example-ttps/templating/loops-integers.yaml b/example-ttps/templating/loops-integers.yaml new file mode 100644 index 00000000..4b403f55 --- /dev/null +++ b/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}} diff --git a/example-ttps/templating/loops-strings.yaml b/example-ttps/templating/loops-strings.yaml new file mode 100644 index 00000000..4e72d323 --- /dev/null +++ b/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}} diff --git a/example-ttps/templating/loops.yaml b/example-ttps/templating/loops.yaml new file mode 100644 index 00000000..fe24e25d --- /dev/null +++ b/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}}