From: Jérémie Astor <fennecdjay@gmail.com>
Date: Tue, 26 Apr 2022 20:09:47 +0000 (+0200)
Subject: add captures docs
X-Git-Url: http://10.10.0.4:5575/?a=commitdiff_plain;h=32ca84132ee2c9c28da7c1d4d955284a95b12fd6;p=gwion.git

add captures docs
---

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