From: jan Jenwa <24357776+jenra-uwu@users.noreply.github.com>
Date: Mon, 16 Jan 2023 18:24:09 +0000 (-0500)
Subject: Added pipe documentation (#15)
X-Git-Url: http://10.10.0.4:5575/?a=commitdiff_plain;h=f0efd348ada4fa97d5b37492ddac389e73536300;p=gwion.git

Added pipe documentation (#15)

* Added Pipes.mdr to document pipes

* Documented multiple underscores in pipes
---

diff --git a/docs/Reference/Functions/Pipes.mdr b/docs/Reference/Functions/Pipes.mdr
new file mode 100644
index 00000000..9a709e78
--- /dev/null
+++ b/docs/Reference/Functions/Pipes.mdr
@@ -0,0 +1,65 @@
+# Pipes
+## Motivation
+Sometimes when writing code, you have a situation such as this:
+```gwion,editable
+fun int incr(int i) {
+  return i + 1;
+}
+
+<<< incr(incr(incr(incr(1)))) >>>;
+```
+
+This code looks rather unappealing due to the nested functions. Instead, you can use pipes!
+
+## Usage
+
+Instead of nesting functions over and over again, you can pipe the functions in a nice line.
+
+```gwion,editable
+fun int incr(int i) {
+  return i + 1;
+}
+
+<<< 1 => incr => incr => incr => incr >>>;
+```
+
+As you can see, the `1` is piped into the `incr` function, and the result of that is piped into the `incr` function, and so on.
+
+### Multiple arguments
+
+Piping works a little differently if your function has multiple arguments. If a function has multiple arguments, there are two ways to pipe.
+
+First off, you can pipe all arguments directly.
+
+```gwion,editable
+fun int add(int i, int j) {
+  return i + j;
+}
+
+<<< (1, 2) => add >>>;
+```
+
+Second off, you can pipe arguments one at a time.
+
+```gwion,editable
+fun int add(int i, int j) {
+  return i + j;
+}
+
+<<< 1 => add(_, 2) >>>;
+<<< 2 => add(1, _) >>>;
+```
+
+The underscore determines where the piped argument goes. In the first line, `1` goes into the first argument, whereas in the second line, `2` goes into the second argument.
+
+You can also have multiple underscores.
+
+```gwion,editable
+fun int add3(int i, int j, int k) {
+  return i + j + k;
+}
+
+<<< (1, 3) => add3(_, 2, _) >>>;
+```
+
+The arguments go into their respective underscores. In this case, `1` goes into the first argument and `3` goes into the third.
\ No newline at end of file
diff --git a/docs/Reference/Functions/list b/docs/Reference/Functions/list
index b2dd05b1..8e9abded 100644
--- a/docs/Reference/Functions/list
+++ b/docs/Reference/Functions/list
@@ -2,3 +2,4 @@ README.md
 function.md
 Lambdas.md
 Variadic.md
+Pipes.md