Document opaque types

Closes https://github.com/gleam-lang/language-tour/issues/63

2 files changed, 60 insertions, 0 deletions

diff --git a/src/content/chapter5_advanced_features/lesson02_use_sugar/code.gleam b/src/content/chapter5_advanced_features/lesson02_use_sugar/code.gleam
new file mode 100644
index 0000000..6c5ccaa
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson02_use_sugar/code.gleam
@@ -0,0 +1,30 @@
+import gleam/io
+import gleam/result
+
+pub fn main() {
+  let x = {
+    use username <- result.try(get_username())
+    use password <- result.try(get_password())
+    use greeting <- result.map(log_in(username, password))
+    greeting <> ", " <> username
+  }
+
+  case x {
+    Ok(greeting) -> io.println(greeting)
+    Error(error) -> io.println("ERROR:" <> error)
+  }
+}
+
+// Here are some pretend functions for this example:
+
+fn get_username() {
+  Ok("alice")
+}
+
+fn get_password() {
+  Ok("hunter2")
+}
+
+fn log_in(_username: String, _password: String) {
+  Ok("Welcome")
+}
diff --git a/src/content/chapter5_advanced_features/lesson02_use_sugar/en.html b/src/content/chapter5_advanced_features/lesson02_use_sugar/en.html
new file mode 100644
index 0000000..e28c843
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson02_use_sugar/en.html
@@ -0,0 +1,30 @@
+<p>
+  The <code>use</code> expression is syntactic sugar for a regular function call
+  and an anonymous function.
+</p>
+
+<p>This code:</p>
+<pre>
+use a, b <- my_function
+next(a)
+next(b)
+</pre>
+
+<p>Expands into this code:</p>
+<pre>
+my_function(fn(a, b) {
+  next(a)
+  next(b)
+})
+</pre>
+
+<p>
+  To ensure that your <code>use</code> code works and is as understandable as
+  possible, the right-hand-side ideally should be a function call rather than a
+  pipeline or other expression, which is typically more difficult to read.
+</p>
+
+<p>
+  <code>use</code> is an expression like everything else in Gleam, so it can be
+  placed within blocks.
+</p>