From 774a35ae21dada36af48ae32c862b22587fba107 Mon Sep 17 00:00:00 2001
From: JJ
Date: Thu, 28 Dec 2023 02:18:50 -0800
Subject: docs: sweeping changes. cement an understanding of error handling,
 async, modules, and unions. rewrite documentation on interfaces. complete the
 introductory overview. many minor cleanups.

---
 std/default/format.pk    |  4 ++--
 std/default/iterators.pk |  4 ++--
 std/default/options.pk   | 24 +++++++++++++++---------
 std/default/results.pk   | 27 ++++++++++++++-------------
 4 files changed, 33 insertions(+), 26 deletions(-)

(limited to 'std')

diff --git a/std/default/format.pk b/std/default/format.pk
index ee8997d..b117632 100644
--- a/std/default/format.pk
+++ b/std/default/format.pk
@@ -7,8 +7,8 @@ pub type Display = interface
   str(Self): str
   dbg(Self): str
 
-## The Debug interface. Broadly implemented for every type with compiler magic,
-## types can (and should) override the generic implementations.
+## The Debug interface. Broadly implemented for every type with compiler magic.
+## Types can (and should) override the generic implementations.
 pub type Debug = interface
   dbg(Self): str
 
diff --git a/std/default/iterators.pk b/std/default/iterators.pk
index f97c61a..f7e4972 100644
--- a/std/default/iterators.pk
+++ b/std/default/iterators.pk
@@ -21,11 +21,11 @@ pub func get[T](self: Iter[T], at: uint): Option[T]
 # todo: implement iter[T](self: ...): Iter[T] funcs
 # todo: efficient functional methods
 
-## The Peek interface. Any type implementing Iter, `peek`, and `peek_nth` is peekable.
+## The Peek interface. Any type implementing `Iter`, `peek`, and `peek_nth` is peekable.
 pub type Peek[T] = interface
   next(mut Self): Option[T]
   peek(mut Self): Option[T]
-  peek_nth(mut Self, n: uint): Option[T]
+  peek_nth(mut Self, int): Option[T]
 
 # todo: implement peek[T](self: Iter[T]): Peek[T]
 # todo: implement Peekable struct
diff --git a/std/default/options.pk b/std/default/options.pk
index 397a8f3..fb696ba 100644
--- a/std/default/options.pk
+++ b/std/default/options.pk
@@ -1,12 +1,12 @@
 ## std/options: Optional types.
 ## This module is imported by default.
 
-import std/format
+use std.format
 
 ## The `Option` type.
 ## A type that represents either the presence or absence of a value.
 pub type Option[T] = union
-  Some: T
+  Some(T)
   None
 
 ## Checks if a type is present within an `Option` type.
@@ -43,7 +43,7 @@ pub func flatmap[T, U](self: Option[T], fn: T -> Option[U]): Option[U] =
   else:
     None
 ## Converts from Option[Option[T]] to Option[T].
-pub func flatten[T](self: Option[Option[T]]): Option[T] = # todo: better name?
+pub func flatten[T](self: Option[Option[T]]): Option[T] =
   match self
   of Some(Some(x)):
     Some(x)
@@ -55,19 +55,25 @@ pub func get_or[T](self: Option[T], default: T): T =
   if self of Some(x): x
   else: default
 ## Directly accesses the inner value. Throws an exception if None.
-pub yeet func `!`[T](self: Option[T]): T =
+pub func ![T](self: Option[T]): T =
   if self of Some(x): x
   else: raise Exception # todo: syntax??
 
 ## Indirect access. Propagates `None`.
-pub macro `?`[T](self: Option[T]) =
+## Parsed by compiler magic.
+pub macro ?[T](self: Option[T]) =
   quote:
-    match self
+    match `self`
     of Some(x): x
     of None: return None
 
+## Syntactic sugar for optional type declarations.
+pub macro ?(T: type) =
+  quote:
+    Option[`T`]
+
 ## Overloads the `==` operation for use on Options.
-pub func `==`[T](a, b: Option[T]): bool =
+pub func ==[T](a, b: Option[T]): bool =
   match (a, b)
   of (Some(x), Some(y)):
     x == y
@@ -77,9 +83,9 @@ pub func `==`[T](a, b: Option[T]): bool =
 ## Overloads the `str()` function for use on Options.
 pub func str[T](self: Option[T]): str =
   if self of Some(x):
-    fmt("some({})", x.str)
+    fmt("Some({})", x.str)
   else:
-    "none"
+    "None"
 
 examples:
   let x = Some(42)
diff --git a/std/default/results.pk b/std/default/results.pk
index 8faf0c0..8e21234 100644
--- a/std/default/results.pk
+++ b/std/default/results.pk
@@ -1,13 +1,12 @@
 ## std/results: Result types.
 ## This module is imported by default.
 
-import std/[options, format]
+use std[options, format]
 
-## The Result type.
-## A type that represents either success or failure.
+## The Result type. Represents either success or failure.
 pub type Result[T, E] = union
-  Okay: T
-  Error: E
+  Okay(T)
+  Error(E)
 
 ## The Err interface. Useful for dynamically dispatching errors.
 pub type Err = interface
@@ -52,7 +51,7 @@ pub func map[T, E, U](self: Result[T, E], fn: T -> U): Result[U, E] =
 pub func map_err[T, E, F](self: Result[T, E], fn: E -> F): Result[T, F] =
   match self
   of Error(e):
-    Error(e.fn)
+    Error(fn(e))
   of Okay(x):
     Okay(x)
 
@@ -92,25 +91,27 @@ pub func transpose[T, E](self: Option[Result[T, E]], error: E): Result[Option[T]
 pub func get_or[T, E](self: Result[T, E], default: T): T =
   if self of Okay(x): x
   else: default
+
 ## Directly accesses the inner value. Throws an exception if `Error`.
-pub yeet func `!`[T, E](self: Result[T, E]): T =
+pub func ![T, E](self: Result[T, E]): T =
   match self
   of Okay(x): x
-  of Error(e): raise Exception(e) # todo: syntax??
-pub yeet func get_err[T, E](self: Result[T, E]): E =
+  of Error(e): raise e
+## Directly accesses the inner error. Throws an exception of type T if `Okay`.
+pub func get_err[T, E](self: Result[T, E]): E =
   match self
   of Error(e): e
-  of Okay(x): raise Exception(x) # todo: syntax??
+  of Okay(x): raise x
 
 ## Indirect access. Propagates `Error`.
-macro `?`[T, E](self: Result[T, E]) =
+pub macro ?[T, E](self: Result[T, E]) =
   quote:
-    match self
+    match `self`
     of Okay(x): x
     of Error(e): return Error(e)
 
 ## Overloads the `==` operation for use on Results.
-pub func `==`[T, E, F](a: Result[T, E], b: Result[T, F]): bool =
+pub func ==[T, E, F](a: Result[T, E], b: Result[T, F]): bool =
   match (a, b)
   of (Okay(x), Okay(y)):
     x == y
-- 
cgit v1.2.3-70-g09d2