More on functions

10 files changed, 168 insertions, 6 deletions

diff --git a/lessons/src/lesson014_higher_order_functions/code.gleam b/lessons/src/lesson014_higher_order_functions/code.gleam
index f453975..e3fb3e7 100644
--- a/lessons/src/lesson014_higher_order_functions/code.gleam
+++ b/lessons/src/lesson014_higher_order_functions/code.gleam
@@ -9,10 +9,10 @@ pub fn main() {
   io.debug(function(100))
 }
 
-fn twice(a: Int, function: fn(Int) -> Int) -> Int {
-  function(function(a))
+fn twice(argument: Int, function: fn(Int) -> Int) -> Int {
+  function(function(argument))
 }
 
-fn add_one(a: Int) -> Int {
-  a + 1
+fn add_one(argument: Int) -> Int {
+  argument + 1
 }
diff --git a/lessons/src/lesson015_anonymous_functions/code.gleam b/lessons/src/lesson015_anonymous_functions/code.gleam
index 9f536d9..2b037e0 100644
--- a/lessons/src/lesson015_anonymous_functions/code.gleam
+++ b/lessons/src/lesson015_anonymous_functions/code.gleam
@@ -9,6 +9,6 @@ pub fn main() {
   io.debug(twice(1, fn(a) { a * 2 }))
 }
 
-fn twice(a: Int, function: fn(Int) -> Int) -> Int {
-  function(function(a))
+fn twice(argument: Int, function: fn(Int) -> Int) -> Int {
+  function(function(argument))
 }
diff --git a/lessons/src/lesson017_generic_functions/code.gleam b/lessons/src/lesson017_generic_functions/code.gleam
new file mode 100644
index 0000000..e232bf8
--- /dev/null
+++ b/lessons/src/lesson017_generic_functions/code.gleam
@@ -0,0 +1,19 @@
+import gleam/io
+
+pub fn main() {
+  let add_one = fn(x) { x + 1 }
+  let exclaim = fn(x) { x <> "!" }
+
+  // Invalid, Int and String are not the same type
+  // twice(10, exclaim)
+
+  // Here the type variable is replaced by the type Int
+  io.debug(twice(10, add_one))
+
+  // Here the type variable is replaced by the type String
+  io.debug(twice("Hello", exclaim))
+}
+
+fn twice(argument: value, function: fn(value) -> value) -> value {
+  function(function(argument))
+}
diff --git a/lessons/src/lesson017_generic_functions/text.html b/lessons/src/lesson017_generic_functions/text.html
new file mode 100644
index 0000000..1369c93
--- /dev/null
+++ b/lessons/src/lesson017_generic_functions/text.html
@@ -0,0 +1,25 @@
+<p>
+  Up until now each function has accepted precisely one type for each of its
+  arguments.
+</p>
+<p>
+  The <code>twice</code> function for example only worked with functions that
+  would take and return ints. This is overly restrictive, it should be possible
+  to use this function with any type, so long as the function and the initial
+  value are compatible.
+</p>
+<p>
+  To enable this Gleam support <em>generics</em>, also known as <em>parametric
+  polymorphism</em>.
+</p>
+<p>
+  This works by instead of specifying a concrete type, a type variable is used
+  which stands in for whatever specific type is being used when the function is
+  called. These type variable are written with a lowercase name.
+</p>
+<p>
+  Type variables are not like an <code>any</code> type, they get replaced with a
+  specific type each time the function is called. Try uncommenting
+  <code>twice(10, exclaim)</code> to see the compiler error from trying to use a
+  type variable as an int and a string at the same time.
+</p>
diff --git a/lessons/src/lesson018_pipelines/code.gleam b/lessons/src/lesson018_pipelines/code.gleam
new file mode 100644
index 0000000..ec9b805
--- /dev/null
+++ b/lessons/src/lesson018_pipelines/code.gleam
@@ -0,0 +1,19 @@
+import gleam/io
+import gleam/string
+
+pub fn main() {
+  // Without the pipe operator
+  io.debug(string.drop_left(string.drop_right("Hello, Joe!", 1), 7))
+
+  // With the pipe operator
+  "Hello, Mike!"
+  |> string.drop_right(1)
+  |> string.drop_left(7)
+  |> io.debug
+
+  // Changing order with function capturing
+  "1"
+  |> string.append("2")
+  |> string.append("3", _)
+  |> io.debug
+}
diff --git a/lessons/src/lesson018_pipelines/text.html b/lessons/src/lesson018_pipelines/text.html
new file mode 100644
index 0000000..783ade9
--- /dev/null
+++ b/lessons/src/lesson018_pipelines/text.html
@@ -0,0 +1,25 @@
+<p>
+  It's common to want to call a series of functions, passing the result of one
+  to the next. With the regular function call syntax this can be a little
+  difficult to read as you have to read the code from the inside out.
+</p>
+<p>
+  Gleam's pipe operator <code>|></code> helps with this problem by allowing you
+  to write code top-to-bottom.
+</p>
+<p>
+  The pipe operator takes the result of the expression on its left and passes it
+  as an argument to the function on its right.
+</p>
+<p>
+  It will first check to see if the left-hand value could be used as the first
+  argument to the call. For example, <code>a |> b(1, 2)</code> would become
+  <code>b(a, 1, 2)</code>. If not, it falls back to calling the result of the
+  right-hand side as a function, e.g., <code>b(1, 2)(a)</code>
+</p>
+<p>
+  Gleam code is typically written with the "subject" of the function as the
+  first argument, to make it easier to pipe. If you wish to pipe to a different
+  position then a function capture can be used to insert the argument to the
+  desired position.
+</p>
diff --git a/lessons/src/lesson019_labelled_arguments/code.gleam b/lessons/src/lesson019_labelled_arguments/code.gleam
new file mode 100644
index 0000000..25bb8c1
--- /dev/null
+++ b/lessons/src/lesson019_labelled_arguments/code.gleam
@@ -0,0 +1,16 @@
+import gleam/io
+
+pub fn main() {
+  // Without using labels
+  io.debug(calculate(1, 2, 3))
+
+  // Using the labels
+  io.debug(calculate(1, add: 2, multiply: 3))
+
+  // Using the labels in a different order
+  io.debug(calculate(1, multiply: 3, add: 2))
+}
+
+fn calculate(value: Int, add addend: Int, multiply multiplier: Int) {
+  value * multiplier + addend
+}
diff --git a/lessons/src/lesson019_labelled_arguments/text.html b/lessons/src/lesson019_labelled_arguments/text.html
new file mode 100644
index 0000000..b1d771c
--- /dev/null
+++ b/lessons/src/lesson019_labelled_arguments/text.html
@@ -0,0 +1,23 @@
+<p>
+  When functions take several arguments it can be difficult to remember what the
+  arguments are, and what order they are expected in.
+</p>
+<p>
+  To help with this Gleam supports labelled arguments, where function arguments
+  are given an external label in addition to their internal name. These labels
+  are written before the argument name in the function definition.
+</p>
+<p>
+  When labelled arguments are used the order of the arguments does not matter,
+  but all unlabelled arguments must come before labelled arguments.
+</p>
+<p>
+  There is no performance cost to using labelled arguments, it does not allocate
+  a dictionary or perform any other runtime work.
+</p>
+<p>
+  Labels are optional when calling a function, it is up to the programmer to
+  decide what is clearest in their code.
+</p>
+
+
diff --git a/lessons/src/lesson099_documentation_comments/code.gleam b/lessons/src/lesson099_documentation_comments/code.gleam
new file mode 100644
index 0000000..a84dce6
--- /dev/null
+++ b/lessons/src/lesson099_documentation_comments/code.gleam
@@ -0,0 +1,19 @@
+//// A module containing some unusual functions and types.
+
+/// A type where the value can never be constructed.
+/// Can you work out why?
+pub type Never {
+  Never(Never)
+}
+
+/// Call a function twice with an initial value.
+///
+pub fn twice(argument: value, function: fn(value) -> value) -> value {
+  function(function(argument))
+}
+
+/// Call a function three times with an initial value.
+///
+pub fn thrice(argument: value, function: fn(value) -> value) -> value {
+  function(function(function(argument)))
+}
diff --git a/lessons/src/lesson099_documentation_comments/text.html b/lessons/src/lesson099_documentation_comments/text.html
new file mode 100644
index 0000000..c27bac6
--- /dev/null
+++ b/lessons/src/lesson099_documentation_comments/text.html
@@ -0,0 +1,16 @@
+<p>
+  Documentation and comments are important tools for making your code easier to
+  work with and understand.
+</p>
+<p>
+  As well as regular <code>//</code> comments Gleam has <code>///</code> and
+  <code>////</code> comments which are used for attaching documentation to code.
+</p>
+<p>
+  <code>///</code> is used for documenting types and functions, and should be
+  placed immediately before the type or function it is documenting.
+</p>
+<p>
+  <code>////</code> is used for documenting modules, and should be placed
+  at the top of the module.
+</p>