doc: added a new exc. 1 to serve as an introduction to the cli, added documentation on discard

4 files changed, 70 insertions, 1 deletions

diff --git a/TUTORIAL.md b/TUTORIAL.md
index 4ae36db..e0017d6 100644
--- a/TUTORIAL.md
+++ b/TUTORIAL.md
@@ -387,6 +387,34 @@ x saved
 () : Nil
 ```
 
+Because you might want to use print several times in
+consequence, but putting them in a list makes the type
+checker look at you weird, the standard library offers
+the convenience function `discard`, which takes anything
+as arguments and returns nil.
+
+Here's an example that shows why you might want to use
+discard:
+```console
+> ((print 1) (print 2))
+Type error: invalid operator: '(print 1)'
+expected: '(_ -> _)'
+found: 'Nil'
+> (quote (print 1) (print 2))
+1
+2
+(quote () ()) : (Quote (Nil Nil))
+```
+As you can see, the return type of the latter try at using
+print twice looks horrible.
+```console
+> (discard (print 1) (print 2))
+1
+2
+() : Nil
+```
+That looks better!
+
 
 Exercises
 =========
@@ -396,7 +424,31 @@ language. The solutions can be found in the `solutions`
 folder under the project root.
 
 
-Exercise 1: Fibonacci sequence
+Exercise 1: Running code
+------------------------
+
+Write a function `cond-add-inv` in a file called `a.slip`.
+It should take an integer and a boolean argument, and if the
+boolean argument is true, return the additive inverse of the
+given integer, otherwise return the given integer without
+modification.
+
+Then, in a file `b.slip`, use the function `cond-add-inv` to
+first print the inverse of 7 and then print 7 without taking
+its inverse.
+
+This should make you familiar with integers, conditional
+logic and using the `myslip` program to link together your
+program from files.
+
+As a bonus, you can use the if-statement provided by the
+standard library, so now you know it works too when linking
+together multiple files. As a superbonus"challenge", you
+may want to try out the `--babysteps` feature
+(see `myslip --help`).
+
+
+Exercise 2: Fibonacci sequence
 ------------------------------
 
 Write a function that calculates the n:th fibonacci number,
diff --git a/solutions/cond-add-inv/a.slip b/solutions/cond-add-inv/a.slip
new file mode 100644
index 0000000..ac11370
--- /dev/null
+++ b/solutions/cond-add-inv/a.slip
@@ -0,0 +1,7 @@
+
+(let cond-add-inv
+  (fn (x cond) (Int Bool) Int
+    (if cond (* -1 x) x)
+  )
+)
+
diff --git a/solutions/cond-add-inv/b.slip b/solutions/cond-add-inv/b.slip
new file mode 100644
index 0000000..af4a995
--- /dev/null
+++ b/solutions/cond-add-inv/b.slip
@@ -0,0 +1,5 @@
+
+(discard
+  (print (cond-add-inv 7 true))
+  (print (cond-add-inv 7 false)))
+
diff --git a/solutions/cond-add-inv/execution.sh b/solutions/cond-add-inv/execution.sh
new file mode 100644
index 0000000..6567131
--- /dev/null
+++ b/solutions/cond-add-inv/execution.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# Here's a way to link a.slip and maintaining the stdlib in
+# use without changing working directory, then using a.slip in b.slip
+myslip -l solutions/cond-add-inv/a.slip solutions/cond-add-inv/b.slip