thoughts on error handling and option and result libraries

1 files changed, 24 insertions, 0 deletions

diff --git a/ERRORS.md b/ERRORS.md
new file mode 100644
index 0000000..4a4b206
--- /dev/null
+++ b/ERRORS.md
@@ -0,0 +1,24 @@
+# Error Handling
+
+Error handling should perhaps be abstracted into a more general effects system.
+But if not, then this document lays out some potential ideas.
+
+---
+
+```puck
+```
+
+Puck provides [`Option[T]`](std/default/options.pk) and a [`Result[T, E]`](std/default/results.pk) types, imported by default. These are `union` types and so must be pattern matched upon to be useful: but the standard library provides a bevy of helper functions.
+
+Two in particular are of note. The `?` operator unwraps a Result or propagates its error up a function call. The `!` operator unwraps an Option or Result directly or throws an exception in the case of None or Error.
+
+```puck
+```
+
+Errors raised by the `!` operator must be explicitly caught and handled via a `try/catch/finally` statement.
+
+If an exception is not handled within a function body, the function must be explicitly marked as a throwing function via the `yeet` prefix (final name to be determined). The compiler will statically determine which exceptions in particular are thrown from any given function.
+
+This creates a distinction between two types of error handling, working in sync: functional error handling with [Option](https://en.wikipedia.org/wiki/Option_type) and [Result](https://en.wikipedia.org/wiki/Result_type) types, and object-oriented error handling with [nullable types](https://en.wikipedia.org/wiki/Nullable_type) and [exceptions](https://en.wikipedia.org/wiki/Exception_handling). These styles may be swapped between with minimal syntax overhead. Libraries, however, should universally use Options and Results, as this provides best for both usages.
+
+References: [std/options](std/default/options.pk), [std/results](std/default/results.pk), [Error Handling in Swift](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling) (shamelessly stolen)