From 938f49fc7835501192ccc7db7c1ab3174f050b34 Mon Sep 17 00:00:00 2001 From: Louis Pilfold Date: Tue, 20 Feb 2024 12:20:16 +0000 Subject: Let assert --- .../lesson04_externals/code.gleam | 17 --------------- .../lesson04_externals/en.html | 25 ---------------------- .../lesson04_let_assert/code.gleam | 16 ++++++++++++++ .../lesson04_let_assert/en.html | 15 +++++++++++++ .../lesson05_externals/code.gleam | 17 +++++++++++++++ .../lesson05_externals/en.html | 25 ++++++++++++++++++++++ .../lesson05_multi_target_externals/code.gleam | 11 ---------- .../lesson05_multi_target_externals/en.html | 22 ------------------- .../lesson06_external_gleam_fallbacks/code.gleam | 18 ---------------- .../lesson06_external_gleam_fallbacks/en.html | 13 ----------- .../lesson06_multi_target_externals/code.gleam | 11 ++++++++++ .../lesson06_multi_target_externals/en.html | 22 +++++++++++++++++++ .../lesson07_external_gleam_fallbacks/code.gleam | 18 ++++++++++++++++ .../lesson07_external_gleam_fallbacks/en.html | 13 +++++++++++ 14 files changed, 137 insertions(+), 106 deletions(-) delete mode 100644 src/content/chapter5_advanced_features/lesson04_externals/code.gleam delete mode 100644 src/content/chapter5_advanced_features/lesson04_externals/en.html create mode 100644 src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam create mode 100644 src/content/chapter5_advanced_features/lesson04_let_assert/en.html create mode 100644 src/content/chapter5_advanced_features/lesson05_externals/code.gleam create mode 100644 src/content/chapter5_advanced_features/lesson05_externals/en.html delete mode 100644 src/content/chapter5_advanced_features/lesson05_multi_target_externals/code.gleam delete mode 100644 src/content/chapter5_advanced_features/lesson05_multi_target_externals/en.html delete mode 100644 src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/code.gleam delete mode 100644 src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/en.html create mode 100644 src/content/chapter5_advanced_features/lesson06_multi_target_externals/code.gleam create mode 100644 src/content/chapter5_advanced_features/lesson06_multi_target_externals/en.html create mode 100644 src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/code.gleam create mode 100644 src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/en.html (limited to 'src/content/chapter5_advanced_features') diff --git a/src/content/chapter5_advanced_features/lesson04_externals/code.gleam b/src/content/chapter5_advanced_features/lesson04_externals/code.gleam deleted file mode 100644 index 1101b82..0000000 --- a/src/content/chapter5_advanced_features/lesson04_externals/code.gleam +++ /dev/null @@ -1,17 +0,0 @@ -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: -// export function now() { -// return new Date(); -// } - -pub fn main() { - io.debug(now()) -} diff --git a/src/content/chapter5_advanced_features/lesson04_externals/en.html b/src/content/chapter5_advanced_features/lesson04_externals/en.html deleted file mode 100644 index 8815fa7..0000000 --- a/src/content/chapter5_advanced_features/lesson04_externals/en.html +++ /dev/null @@ -1,25 +0,0 @@ -

- 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 external functions and external types allow us to - import and use this non-Gleam code. -

-

- An external type is one that has no constructors. Gleam doesn't know what - shape it has or how to create one, it only knows that it exists. -

-

- An external function is one that has the @external attribute on - it, directing the compiler to use the specified module function as the - implementation, instead of Gleam code. -

-

- 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! -

-

- External functions are useful but should be used sparingly. Prefer to write - Gleam code where possible. -

diff --git a/src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam b/src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam new file mode 100644 index 0000000..2ba907a --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam @@ -0,0 +1,16 @@ +import gleam/io + +pub fn main() { + let a = unsafely_get_first_element([123]) + io.debug(a) + + let b = unsafely_get_first_element([]) + io.debug(b) +} + +pub fn unsafely_get_first_element(items: List(a)) -> a { + // This will panic if the list is empty. + // A regular `let` would not permit this partial pattern + let assert [first, ..] = items + first +} diff --git a/src/content/chapter5_advanced_features/lesson04_let_assert/en.html b/src/content/chapter5_advanced_features/lesson04_let_assert/en.html new file mode 100644 index 0000000..29fd06c --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson04_let_assert/en.html @@ -0,0 +1,15 @@ +

+ let assert is the final way to intentionally crash your Gleam + program. It is similar to the panic keyword in that it crashes + when the program has reached a point that should never be reached. +

+

+ let assert is similar to let in that it is a way to + assign values to variables, but it is different in that the pattern can be + partial. The pattern does not need to match every possible value of the + type being assigned. +

+

+ Like panic this feature should be used sparingly, and likely not + at all in libraries. +

diff --git a/src/content/chapter5_advanced_features/lesson05_externals/code.gleam b/src/content/chapter5_advanced_features/lesson05_externals/code.gleam new file mode 100644 index 0000000..1101b82 --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson05_externals/code.gleam @@ -0,0 +1,17 @@ +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: +// export function now() { +// return new Date(); +// } + +pub fn main() { + io.debug(now()) +} diff --git a/src/content/chapter5_advanced_features/lesson05_externals/en.html b/src/content/chapter5_advanced_features/lesson05_externals/en.html new file mode 100644 index 0000000..8815fa7 --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson05_externals/en.html @@ -0,0 +1,25 @@ +

+ 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 external functions and external types allow us to + import and use this non-Gleam code. +

+

+ An external type is one that has no constructors. Gleam doesn't know what + shape it has or how to create one, it only knows that it exists. +

+

+ An external function is one that has the @external attribute on + it, directing the compiler to use the specified module function as the + implementation, instead of Gleam code. +

+

+ 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! +

+

+ External functions are useful but should be used sparingly. Prefer to write + Gleam code where possible. +

diff --git a/src/content/chapter5_advanced_features/lesson05_multi_target_externals/code.gleam b/src/content/chapter5_advanced_features/lesson05_multi_target_externals/code.gleam deleted file mode 100644 index b62a735..0000000 --- a/src/content/chapter5_advanced_features/lesson05_multi_target_externals/code.gleam +++ /dev/null @@ -1,11 +0,0 @@ -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_advanced_features/lesson05_multi_target_externals/en.html b/src/content/chapter5_advanced_features/lesson05_multi_target_externals/en.html deleted file mode 100644 index 6e02d36..0000000 --- a/src/content/chapter5_advanced_features/lesson05_multi_target_externals/en.html +++ /dev/null @@ -1,22 +0,0 @@ -

- Multiple external implementations can be specified for the same function, - enabling the function to work on both Erlang and JavaScript. -

-

- If a function doesn't have an implementation for the currently compiled-for - target then the compiler will return an error. -

-

- You should try to implement functions 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. -

-

- Libraries that make use of concurrent IO will typically have to decide whether - they support Erlang or JavaScript, and document this in their README. -

diff --git a/src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/code.gleam b/src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/code.gleam deleted file mode 100644 index a97b8fc..0000000 --- a/src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/code.gleam +++ /dev/null @@ -1,18 +0,0 @@ -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_advanced_features/lesson06_external_gleam_fallbacks/en.html b/src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/en.html deleted file mode 100644 index 243c7ea..0000000 --- a/src/content/chapter5_advanced_features/lesson06_external_gleam_fallbacks/en.html +++ /dev/null @@ -1,13 +0,0 @@ -

- 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. -

-

- 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. -

diff --git a/src/content/chapter5_advanced_features/lesson06_multi_target_externals/code.gleam b/src/content/chapter5_advanced_features/lesson06_multi_target_externals/code.gleam new file mode 100644 index 0000000..b62a735 --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson06_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_advanced_features/lesson06_multi_target_externals/en.html b/src/content/chapter5_advanced_features/lesson06_multi_target_externals/en.html new file mode 100644 index 0000000..6e02d36 --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson06_multi_target_externals/en.html @@ -0,0 +1,22 @@ +

+ Multiple external implementations can be specified for the same function, + enabling the function to work on both Erlang and JavaScript. +

+

+ If a function doesn't have an implementation for the currently compiled-for + target then the compiler will return an error. +

+

+ You should try to implement functions 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. +

+

+ Libraries that make use of concurrent IO will typically have to decide whether + they support Erlang or JavaScript, and document this in their README. +

diff --git a/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/code.gleam b/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/code.gleam new file mode 100644 index 0000000..a97b8fc --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson07_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_advanced_features/lesson07_external_gleam_fallbacks/en.html b/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/en.html new file mode 100644 index 0000000..243c7ea --- /dev/null +++ b/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/en.html @@ -0,0 +1,13 @@ +

+ 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. +

+

+ 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. +

-- cgit v1.2.3