From 311cdf00ab44d2776d0a0319f5684e2350acad69 Mon Sep 17 00:00:00 2001
From: Pete Davison <pd93.uk@outlook.com>
Date: Thu, 21 Dec 2023 10:17:18 +0000
Subject: [PATCH] docs: add information about loops

---
 docs/docs/experiments/any_variables.mdx | 59 ++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/docs/docs/experiments/any_variables.mdx b/docs/docs/experiments/any_variables.mdx
index b3648ccde6..61c95f752b 100644
--- a/docs/docs/experiments/any_variables.mdx
+++ b/docs/docs/experiments/any_variables.mdx
@@ -49,7 +49,7 @@ tasks:
       - 'echo {{add .INT .FLOAT}}'
 ```
 
-Loops:
+Ranging:
 
 ```yaml
 version: 3
@@ -62,7 +62,58 @@ tasks:
       - 'echo {{range .ARRAY}}{{.}}{{end}}'
 ```
 
-etc.
+There are many more templating functions which can be used with the new types of
+variables. For a full list, see the
+[slim-sprig][slim-sprig] documentation.
+
+## Looping over variables
+
+Previously, you would have to use a delimiter separated string to loop over an
+arbitrary list of items in a variable and split them by using the `split` subkey
+to specify the delimiter:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      LIST: 'foo,bar,baz'
+    cmds:
+      - for:
+          var: LIST
+          split: ','
+        cmd: echo {{.ITEM}}
+```
+
+Because this experiment adds support for array variables, the `for` keyword has
+been updated to support looping over arrays directly:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      LIST: [foo, bar, baz]
+    cmds:
+      - for:
+          var: LIST
+        cmd: echo {{.ITEM}}
+```
+
+String splitting is still supported and remember that for simple cases, you have
+always been able to loop over an array without using variables at all:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    cmds:
+      - for: [foo, bar, baz]
+        cmd: echo {{.ITEM}}
+```
 
 ## Migration
 
@@ -103,3 +154,7 @@ task:
 If your current Taskfile contains a string variable that begins with a `$`, you
 will now need to escape the `$` with a backslash (`\`) to stop Task from
 executing it as a command.
+
+<!-- prettier-ignore-start -->
+[slim-sprig]: https://go-task.github.io/slim-sprig/
+<!-- prettier-ignore-end -->