aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/content/chapter5_advance_features/lesson00_use/code.gleam38
-rw-r--r--src/content/chapter5_advance_features/lesson00_use/text.html31
-rw-r--r--src/content/chapter5_advance_features/lesson01_use_continued/code.gleam30
-rw-r--r--src/content/chapter5_advance_features/lesson01_use_continued/text.html30
-rw-r--r--src/content/chapter5_advance_features/lesson02_todo/code.gleam (renamed from src/content/chapter5_advance_features/lesson00_todo/code.gleam)0
-rw-r--r--src/content/chapter5_advance_features/lesson02_todo/text.html (renamed from src/content/chapter5_advance_features/lesson00_todo/text.html)0
-rw-r--r--src/content/chapter5_advance_features/lesson03_panic/code.gleam (renamed from src/content/chapter5_advance_features/lesson01_panic/code.gleam)0
-rw-r--r--src/content/chapter5_advance_features/lesson03_panic/text.html (renamed from src/content/chapter5_advance_features/lesson01_panic/text.html)0
-rw-r--r--src/content/chapter5_advance_features/lesson04_externals/code.gleam18
-rw-r--r--src/content/chapter5_advance_features/lesson04_externals/text.html25
-rw-r--r--src/content/chapter5_advance_features/lesson05_multi_target_externals/code.gleam11
-rw-r--r--src/content/chapter5_advance_features/lesson05_multi_target_externals/text.html22
-rw-r--r--src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/code.gleam18
-rw-r--r--src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/text.html13
14 files changed, 236 insertions, 0 deletions
diff --git a/src/content/chapter5_advance_features/lesson00_use/code.gleam b/src/content/chapter5_advance_features/lesson00_use/code.gleam
new file mode 100644
index 0000000..37624ab
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson00_use/code.gleam
@@ -0,0 +1,38 @@
+import gleam/io
+import gleam/result
+
+pub fn main() {
+ io.debug(without_use())
+ io.debug(with_use())
+}
+
+pub fn without_use() {
+ result.try(get_usename(), fn(username) {
+ result.try(get_password(), fn(password) {
+ result.map(log_in(username, password), fn(greeting) {
+ greeting <> ", " <> username
+ })
+ })
+ })
+}
+
+pub fn with_use() {
+ use username <- result.try(get_usename())
+ use password <- result.try(get_password())
+ use greeting <- result.map(log_in(username, password))
+ greeting <> ", " <> username
+}
+
+// Here are some pretend functions for this example:
+
+fn get_usename() {
+ Ok("alice")
+}
+
+fn get_password() {
+ Ok("hunter2")
+}
+
+fn log_in(_username: String, _password: String) {
+ Ok("Welcome")
+}
diff --git a/src/content/chapter5_advance_features/lesson00_use/text.html b/src/content/chapter5_advance_features/lesson00_use/text.html
new file mode 100644
index 0000000..e295dda
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson00_use/text.html
@@ -0,0 +1,31 @@
+<p>
+ Gleam lacks exceptions, macros, type classes, early returns, and a variety of
+ other features, instead going all-in with just first-class-functions and
+ pattern matching. This makes Gleam code easier to understand, but it can
+ sometimes result in excessive indentation.
+</p>
+<p>
+ Gleam's use expression helps out here by enabling us to write code that uses
+ callbacks in an unindented style, as shown in the code window.
+</p>
+
+<p>
+ The higher order function being called goes on the right hand side of the
+ <code>&lt;-</code> operator. It must take a callback function as its final
+ argument.
+</p>
+<p>
+ The argument names for the callback function go on the left hand side of the
+ <code>&lt;-</code> operator. The function can take any number of arguments,
+ including zero.
+</p>
+<p>
+ All the following code in the <code class="hljs">{}</code> block becomes the
+ body of the callback function.
+</p>
+<p>
+ This is a very capable and useful feature, but excessive application of
+ <code>use</code> may result in code that is unclear otherwise, especially to
+ beginners. Often using the regular function call syntax will result in more
+ approachable code!
+</p>
diff --git a/src/content/chapter5_advance_features/lesson01_use_continued/code.gleam b/src/content/chapter5_advance_features/lesson01_use_continued/code.gleam
new file mode 100644
index 0000000..ac61062
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson01_use_continued/code.gleam
@@ -0,0 +1,30 @@
+import gleam/io
+import gleam/result
+
+pub fn main() {
+ let x = {
+ use username <- result.try(get_usename())
+ 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_usename() {
+ Ok("alice")
+}
+
+fn get_password() {
+ Ok("hunter2")
+}
+
+fn log_in(_username: String, _password: String) {
+ Ok("Welcome")
+}
diff --git a/src/content/chapter5_advance_features/lesson01_use_continued/text.html b/src/content/chapter5_advance_features/lesson01_use_continued/text.html
new file mode 100644
index 0000000..e28c843
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson01_use_continued/text.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>
diff --git a/src/content/chapter5_advance_features/lesson00_todo/code.gleam b/src/content/chapter5_advance_features/lesson02_todo/code.gleam
index d5abe8f..d5abe8f 100644
--- a/src/content/chapter5_advance_features/lesson00_todo/code.gleam
+++ b/src/content/chapter5_advance_features/lesson02_todo/code.gleam
diff --git a/src/content/chapter5_advance_features/lesson00_todo/text.html b/src/content/chapter5_advance_features/lesson02_todo/text.html
index 4a2c433..4a2c433 100644
--- a/src/content/chapter5_advance_features/lesson00_todo/text.html
+++ b/src/content/chapter5_advance_features/lesson02_todo/text.html
diff --git a/src/content/chapter5_advance_features/lesson01_panic/code.gleam b/src/content/chapter5_advance_features/lesson03_panic/code.gleam
index fce9d66..fce9d66 100644
--- a/src/content/chapter5_advance_features/lesson01_panic/code.gleam
+++ b/src/content/chapter5_advance_features/lesson03_panic/code.gleam
diff --git a/src/content/chapter5_advance_features/lesson01_panic/text.html b/src/content/chapter5_advance_features/lesson03_panic/text.html
index 843a65b..843a65b 100644
--- a/src/content/chapter5_advance_features/lesson01_panic/text.html
+++ b/src/content/chapter5_advance_features/lesson03_panic/text.html
diff --git a/src/content/chapter5_advance_features/lesson04_externals/code.gleam b/src/content/chapter5_advance_features/lesson04_externals/code.gleam
new file mode 100644
index 0000000..be4aff0
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson04_externals/code.gleam
@@ -0,0 +1,18 @@
+import gleam/io
+
+// A type with no Gleam constructors
+pub type DateTime
+
+// An external function that creates an instance of the type
+@external(javascript, "./my_package_ffi.mjs", "now")
+pub fn now() -> DateTime
+
+// The `now` function in `./my_package_ffi.mjs` looks like this:
+// external function now() {
+// return new Date();
+// }
+
+pub fn main() {
+ io.debug(now())
+}
+
diff --git a/src/content/chapter5_advance_features/lesson04_externals/text.html b/src/content/chapter5_advance_features/lesson04_externals/text.html
new file mode 100644
index 0000000..81202d6
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson04_externals/text.html
@@ -0,0 +1,25 @@
+<p>
+ Sometimes in our projects we want to use code written in other languages, most
+ commonly Erlang and JavaScript, depending on which runtime is being used.
+ Gleam's <em>external functions</em> and <em>external types</em> allow us to
+ import and use this non-Gleam code.
+</p>
+<p>
+ An external type is a one that has no constructors. Gleam doesn't know what
+ shape it has or how to create one, it only knows that it exists.
+</p>
+<p>
+ An external function is one that has the <code>@external</code> attribute on
+ it, directing the compiler to use the specified module function as the
+ implementation, instead of Gleam code.
+</p>
+<p>
+ The compiler can't tell the types of functions written in other languages, so
+ when the external attribute is given type annotations must be provided. Gleam
+ trusts that the type given is correct so an inaccurate type annotation can
+ result in unexpected behaviour and crashes at runtime. Be careful!
+</p>
+<p>
+ External functions are useful but should be used sparingly. Prefer to write
+ Gleam code where possible.
+</p>
diff --git a/src/content/chapter5_advance_features/lesson05_multi_target_externals/code.gleam b/src/content/chapter5_advance_features/lesson05_multi_target_externals/code.gleam
new file mode 100644
index 0000000..b62a735
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson05_multi_target_externals/code.gleam
@@ -0,0 +1,11 @@
+import gleam/io
+
+pub type DateTime
+
+@external(erlang, "calendar", "local_time")
+@external(javascript, "./my_package_ffi.mjs", "now")
+pub fn now() -> DateTime
+
+pub fn main() {
+ io.debug(now())
+}
diff --git a/src/content/chapter5_advance_features/lesson05_multi_target_externals/text.html b/src/content/chapter5_advance_features/lesson05_multi_target_externals/text.html
new file mode 100644
index 0000000..dc10a19
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson05_multi_target_externals/text.html
@@ -0,0 +1,22 @@
+<p>
+ Multiple external implementations can be specified for the same function,
+ enabling the function to work on both Erlang and JavaScript.
+</p>
+<p>
+ If a function doesn't have an implementation for the currently compiled-for
+ target then the compiler will return an error.
+</p>
+<p>
+ You should try to implement functons for all targets, but this isn't always
+ possible due to incompatibilities in how IO and concurreny works in Erlang and
+ JavaScript. With Erlang concurrent IO is handled transparently by the runtime,
+ while in JavaScript concurrent IO requires the use of promises or callbacks.
+ If your code uses the Erlang style it is typically not possible to implement
+ in JavaScript, while if callbacks are used then it won't be compatible with
+ most Gleam and Erlang code as it forces any code that calls the function to
+ also use callbacks.
+</p>
+<p>
+ Libraries that make use of concurrent IO will typically have to decide whether
+ they support Erlang or JavaScript, and document this in their README.
+</p>
diff --git a/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/code.gleam b/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/code.gleam
new file mode 100644
index 0000000..a97b8fc
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/code.gleam
@@ -0,0 +1,18 @@
+import gleam/io
+
+@external(erlang, "lists", "reverse")
+pub fn reverse_list(items: List(e)) -> List(e) {
+ tail_recursive_reverse(items, [])
+}
+
+fn tail_recursive_reverse(items: List(e), reversed: List(e)) -> List(e) {
+ case items {
+ [] -> reversed
+ [first, ..rest] -> tail_recursive_reverse(rest, [first, ..reversed])
+ }
+}
+
+pub fn main() {
+ io.debug(reverse_list([1, 2, 3, 4, 5]))
+ io.debug(reverse_list(["a", "b", "c", "d", "e"]))
+}
diff --git a/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/text.html b/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/text.html
new file mode 100644
index 0000000..243c7ea
--- /dev/null
+++ b/src/content/chapter5_advance_features/lesson06_external_gleam_fallbacks/text.html
@@ -0,0 +1,13 @@
+<p>
+ It's possible for a function to have both a Gleam implementation and an
+ external implementation. If there exists an external implementation for the
+ currently compiled-for target then it will be used, otherwise the Gleam
+ implementation is used.
+</p>
+<p>
+ This may be useful if you have a function that can be implemented in Gleam,
+ but there is an optimised implementation that can be used for one target. For
+ example, the Erlang virtual machine has a built-in list reverse function that
+ is implemented in native code. The code here uses this implementation when
+ running on Erlang, as it is then available.
+</p>