Document opaque types

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

18 files changed, 43 insertions, 0 deletions

diff --git a/src/content/chapter5_advanced_features/lesson00_opaque_types/code.gleam b/src/content/chapter5_advanced_features/lesson00_opaque_types/code.gleam
new file mode 100644
index 0000000..d116b42
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson00_opaque_types/code.gleam
@@ -0,0 +1,26 @@
+import gleam/io
+
+pub fn main() {
+  let positive = new(1)
+  let zero = new(0)
+  let negative = new(-1)
+
+  io.debug(to_int(positive))
+  io.debug(to_int(zero))
+  io.debug(to_int(negative))
+}
+
+pub opaque type PositiveInt {
+  PositiveInt(inner: Int)
+}
+
+pub fn new(i: Int) -> PositiveInt {
+  case i >= 0 {
+    True -> PositiveInt(i)
+    False -> PositiveInt(0)
+  }
+}
+
+pub fn to_int(i: PositiveInt) -> Int {
+  i.inner
+}
diff --git a/src/content/chapter5_advanced_features/lesson00_opaque_types/en.html b/src/content/chapter5_advanced_features/lesson00_opaque_types/en.html
new file mode 100644
index 0000000..dbd362f
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson00_opaque_types/en.html
@@ -0,0 +1,17 @@
+<p>
+  <em>Opaque types</em> are types where a custom type itself is public and can
+  be used by other modules, but the constructors for the type are private and
+  can only be used by the module that defines the type. This prevents other
+  modules from constructing or pattern matching on the type.
+</p>
+<p>
+  This is useful for creating types with <em>smart constructors</em>. A smart
+  constructor is a function that constructs a value of a type, but is more
+  restrictive than if the programmer were to use one of the type's constructors
+  directly. This can be useful for ensuring that the type is used correctly.
+</p>
+<p>
+  For example, this <code>PositiveInt</code> custom type is opaque, so if other
+  modules want to construct one they have to use the <code>new</code> function,
+  which ensures that the integer is positive.
+</p>
diff --git a/src/content/chapter5_advanced_features/lesson00_use/code.gleam b/src/content/chapter5_advanced_features/lesson01_use/code.gleam
index e7b435b..e7b435b 100644
--- a/src/content/chapter5_advanced_features/lesson00_use/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson01_use/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson00_use/en.html b/src/content/chapter5_advanced_features/lesson01_use/en.html
index b8e2641..b8e2641 100644
--- a/src/content/chapter5_advanced_features/lesson00_use/en.html
+++ b/src/content/chapter5_advanced_features/lesson01_use/en.html
diff --git a/src/content/chapter5_advanced_features/lesson01_use_sugar/code.gleam b/src/content/chapter5_advanced_features/lesson02_use_sugar/code.gleam
index 6c5ccaa..6c5ccaa 100644
--- a/src/content/chapter5_advanced_features/lesson01_use_sugar/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson02_use_sugar/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson01_use_sugar/en.html b/src/content/chapter5_advanced_features/lesson02_use_sugar/en.html
index e28c843..e28c843 100644
--- a/src/content/chapter5_advanced_features/lesson01_use_sugar/en.html
+++ b/src/content/chapter5_advanced_features/lesson02_use_sugar/en.html
diff --git a/src/content/chapter5_advanced_features/lesson02_todo/code.gleam b/src/content/chapter5_advanced_features/lesson03_todo/code.gleam
index d5abe8f..d5abe8f 100644
--- a/src/content/chapter5_advanced_features/lesson02_todo/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson03_todo/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson02_todo/en.html b/src/content/chapter5_advanced_features/lesson03_todo/en.html
index 4a2c433..4a2c433 100644
--- a/src/content/chapter5_advanced_features/lesson02_todo/en.html
+++ b/src/content/chapter5_advanced_features/lesson03_todo/en.html
diff --git a/src/content/chapter5_advanced_features/lesson03_panic/code.gleam b/src/content/chapter5_advanced_features/lesson04_panic/code.gleam
index fce9d66..fce9d66 100644
--- a/src/content/chapter5_advanced_features/lesson03_panic/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson04_panic/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson03_panic/en.html b/src/content/chapter5_advanced_features/lesson04_panic/en.html
index c54c217..c54c217 100644
--- a/src/content/chapter5_advanced_features/lesson03_panic/en.html
+++ b/src/content/chapter5_advanced_features/lesson04_panic/en.html
diff --git a/src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam b/src/content/chapter5_advanced_features/lesson05_let_assert/code.gleam
index 2ba907a..2ba907a 100644
--- a/src/content/chapter5_advanced_features/lesson04_let_assert/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson05_let_assert/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson04_let_assert/en.html b/src/content/chapter5_advanced_features/lesson05_let_assert/en.html
index 29fd06c..29fd06c 100644
--- a/src/content/chapter5_advanced_features/lesson04_let_assert/en.html
+++ b/src/content/chapter5_advanced_features/lesson05_let_assert/en.html
diff --git a/src/content/chapter5_advanced_features/lesson05_externals/code.gleam b/src/content/chapter5_advanced_features/lesson06_externals/code.gleam
index 1101b82..1101b82 100644
--- a/src/content/chapter5_advanced_features/lesson05_externals/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson06_externals/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson05_externals/en.html b/src/content/chapter5_advanced_features/lesson06_externals/en.html
index 8815fa7..8815fa7 100644
--- a/src/content/chapter5_advanced_features/lesson05_externals/en.html
+++ b/src/content/chapter5_advanced_features/lesson06_externals/en.html
diff --git a/src/content/chapter5_advanced_features/lesson06_multi_target_externals/code.gleam b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/code.gleam
index b62a735..b62a735 100644
--- a/src/content/chapter5_advanced_features/lesson06_multi_target_externals/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson06_multi_target_externals/en.html b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/en.html
index 6e02d36..6e02d36 100644
--- a/src/content/chapter5_advanced_features/lesson06_multi_target_externals/en.html
+++ b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/en.html
diff --git a/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/code.gleam b/src/content/chapter5_advanced_features/lesson08_external_gleam_fallbacks/code.gleam
index a97b8fc..a97b8fc 100644
--- a/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/code.gleam
+++ b/src/content/chapter5_advanced_features/lesson08_external_gleam_fallbacks/code.gleam
diff --git a/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/en.html b/src/content/chapter5_advanced_features/lesson08_external_gleam_fallbacks/en.html
index 243c7ea..243c7ea 100644
--- a/src/content/chapter5_advanced_features/lesson07_external_gleam_fallbacks/en.html
+++ b/src/content/chapter5_advanced_features/lesson08_external_gleam_fallbacks/en.html