From 32ca84132ee2c9c28da7c1d4d955284a95b12fd6 Mon Sep 17 00:00:00 2001
From: =?utf8?q?J=C3=A9r=C3=A9mie=20Astor?= <fennecdjay@gmail.com>
Date: Tue, 26 Apr 2022 22:09:47 +0200
Subject: [PATCH] add captures docs

---
 docs/Overview/Capture_Lists.mdr | 39 +++++++++++++++++++++++++++++++++
 docs/Overview/list              |  1 +
 2 files changed, 40 insertions(+)
 create mode 100644 docs/Overview/Capture_Lists.mdr

diff --git a/docs/Overview/Capture_Lists.mdr b/docs/Overview/Capture_Lists.mdr
new file mode 100644
index 00000000..34e9299a
--- /dev/null
+++ b/docs/Overview/Capture_Lists.mdr
@@ -0,0 +1,39 @@
+# Capture List
+
+Sometimes in a spork/fork or a lambda expression, there is the need to capture one or more variables.
+Here's how it's done in Gwion:
+
+```gwion,editable
+var int foo, bar;
+
+#! for lambdas
+\ arg0 arg 1 : foo bar : {}
+
+#! for spork
+spork : foo bar : {}
+
+#! for fork
+fork : foo bar : {}
+```
+
+If you want to capture by reference, just prepend the variable name with `&`.
+For example capturing `foo` by reference and `bar` by value:
+
+```gwion,editable
+var int foo, bar;
+
+#! for lambdas
+\ arg0 arg 1 : &foo bar : {}
+
+#! for spork
+spork : &foo bar : {}
+
+#! for fork
+fork : &foo bar : {}
+```
+
+## Why explicit captures?
+
+In some cases you may want to track the value of variable, even a primitive, over time.
+If you capture by value, it would stay the same as when the variable was captured,
+hence sometimes the need to use capture by reference.
diff --git a/docs/Overview/list b/docs/Overview/list
index cf913c70..8e4e4d9b 100644
--- a/docs/Overview/list
+++ b/docs/Overview/list
@@ -6,4 +6,5 @@ globalvalues.md
 Keywords.md
 Make.md
 SpecialWords.md
+Capture_Lists
 Testing.md
-- 
2.43.0