@grain/stdlib 0.6.6 → 0.7.1

package/runtime/debugPrint.gr

@@ -1,3 +1,4 @@
+@noPervasives
 module DebugPrint
 
 from "runtime/numberUtils" include NumberUtils as Utils
@@ -9,6 +10,8 @@ from "runtime/unsafe/memory" include Memory
 foreign wasm fd_write:
   (WasmI32, WasmI32, WasmI32, WasmI32) => WasmI32 from "wasi_snapshot_preview1"
 
+primitive ignore = "@ignore"
+
 @unsafe
 provide let print = (s: String) => {
   let ptr = WasmI32.fromGrain(s)
@@ -26,7 +29,7 @@ provide let print = (s: String) => {
   WasmI32.store(iov, 1n, 12n)
   fd_write(1n, iov, 2n, written)
   Memory.free(buf)
-  void
+  ignore(s)
 }
 
 @unsafe

package/runtime/debugPrint.md

@@ -9,54 +9,54 @@ Functions and constants included in the DebugPrint module.
 ### DebugPrint.**print**
 
 ```grain
-print : (s: String) => Void
+print: (s: String) => Void
 ```
 
 ### DebugPrint.**printI32**
 
 ```grain
-printI32 : (val: WasmI32) => Void
+printI32: (val: WasmI32) => Void
 ```
 
 ### DebugPrint.**printI64**
 
 ```grain
-printI64 : (val: WasmI64) => Void
+printI64: (val: WasmI64) => Void
 ```
 
 ### DebugPrint.**printF32**
 
 ```grain
-printF32 : (val: WasmF32) => Void
+printF32: (val: WasmF32) => Void
 ```
 
 ### DebugPrint.**printF64**
 
 ```grain
-printF64 : (val: WasmF64) => Void
+printF64: (val: WasmF64) => Void
 ```
 
 ### DebugPrint.**toStringI32**
 
 ```grain
-toStringI32 : (val: WasmI32) => String
+toStringI32: (val: WasmI32) => String
 ```
 
 ### DebugPrint.**toStringI64**
 
 ```grain
-toStringI64 : (val: WasmI64) => String
+toStringI64: (val: WasmI64) => String
 ```
 
 ### DebugPrint.**toStringF32**
 
 ```grain
-toStringF32 : (val: WasmF32) => String
+toStringF32: (val: WasmF32) => String
 ```
 
 ### DebugPrint.**toStringF64**
 
 ```grain
-toStringF64 : (val: WasmF64) => String
+toStringF64: (val: WasmF64) => String
 ```
 

package/runtime/equal.gr

@@ -3,7 +3,19 @@ module Equal
 
 from "runtime/unsafe/memory" include Memory
 from "runtime/unsafe/wasmi32" include WasmI32
-use WasmI32.{ (==), (!=), (&), (^), (+), (-), (*), (<), remS as (%), (<<) }
+use WasmI32.{
+  (==),
+  (!=),
+  (&),
+  (^),
+  (+),
+  (-),
+  (*),
+  (<),
+  remS as (%),
+  (<<),
+  (>>),
+}
 from "runtime/unsafe/wasmi64" include WasmI64
 from "runtime/unsafe/wasmf32" include WasmF32
 from "runtime/unsafe/tags" include Tags
@@ -14,6 +26,10 @@ primitive (!) = "@not"
 primitive (||) = "@or"
 primitive (&&) = "@and"
 primitive ignore = "@ignore"
+primitive builtinId = "@builtin.id"
+
+@unsafe
+let _LIST_ID = WasmI32.fromGrain(builtinId("List"))
 
 @unsafe
 let cycleMarker = 0x80000000n
@@ -23,38 +39,47 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
   match (heapTag) {
     t when t == Tags._GRAIN_ADT_HEAP_TAG => {
       // Check if the same constructor variant
-      if (WasmI32.load(xptr, 12n) != WasmI32.load(yptr, 12n)) {
-        false
+      let mut xVariantTag = WasmI32.load(xptr, 12n)
+      let mut yVariantTag = WasmI32.load(yptr, 12n)
+      if (xVariantTag != yVariantTag) {
+        return false
+      }
+
+      // Handle lists separately to avoid stack overflow
+      if (WasmI32.load(xptr, 8n) == _LIST_ID) {
+        if (xVariantTag >> 1n == 1n) return true // End of list
+
+        if (!equalHelp(WasmI32.load(xptr, 20n), WasmI32.load(yptr, 20n))) {
+          return false
+        }
+
+        return equalHelp(WasmI32.load(xptr, 24n), WasmI32.load(yptr, 24n))
       } else {
         let xarity = WasmI32.load(xptr, 16n)
         let yarity = WasmI32.load(yptr, 16n)
 
         // Cycle check
         if ((xarity & cycleMarker) == cycleMarker) {
-          true
-        } else {
-          WasmI32.store(xptr, xarity ^ cycleMarker, 16n)
-          WasmI32.store(yptr, yarity ^ cycleMarker, 16n)
-
-          let mut result = true
-
-          let bytes = xarity * 4n
-          for (let mut i = 0n; i < bytes; i += 4n) {
-            if (
-              !equalHelp(
-                WasmI32.load(xptr + i, 20n),
-                WasmI32.load(yptr + i, 20n)
-              )
-            ) {
-              result = false
-              break
-            }
-          }
-          WasmI32.store(xptr, xarity, 16n)
-          WasmI32.store(yptr, yarity, 16n)
+          return true
+        }
 
-          result
+        WasmI32.store(xptr, xarity ^ cycleMarker, 16n)
+        WasmI32.store(yptr, yarity ^ cycleMarker, 16n)
+
+        let bytes = xarity * 4n
+        for (let mut i = 0n; i < bytes; i += 4n) {
+          if (
+            !equalHelp(WasmI32.load(xptr + i, 20n), WasmI32.load(yptr + i, 20n))
+          ) {
+            WasmI32.store(xptr, xarity, 16n)
+            WasmI32.store(yptr, yarity, 16n)
+            return false
+          }
         }
+        WasmI32.store(xptr, xarity, 16n)
+        WasmI32.store(yptr, yarity, 16n)
+
+        return true
       }
     },
     t when t == Tags._GRAIN_RECORD_HEAP_TAG => {
@@ -63,27 +88,26 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
 
       // Cycle check
       if ((xlength & cycleMarker) == cycleMarker) {
-        true
-      } else {
-        WasmI32.store(xptr, xlength ^ cycleMarker, 12n)
-        WasmI32.store(yptr, ylength ^ cycleMarker, 12n)
-
-        let mut result = true
+        return true
+      }
 
-        let bytes = xlength * 4n
-        for (let mut i = 0n; i < bytes; i += 4n) {
-          if (
-            !equalHelp(WasmI32.load(xptr + i, 16n), WasmI32.load(yptr + i, 16n))
-          ) {
-            result = false
-            break
-          }
+      WasmI32.store(xptr, xlength ^ cycleMarker, 12n)
+      WasmI32.store(yptr, ylength ^ cycleMarker, 12n)
+
+      let bytes = xlength * 4n
+      for (let mut i = 0n; i < bytes; i += 4n) {
+        if (
+          !equalHelp(WasmI32.load(xptr + i, 16n), WasmI32.load(yptr + i, 16n))
+        ) {
+          WasmI32.store(xptr, xlength, 12n)
+          WasmI32.store(yptr, ylength, 12n)
+          return false
         }
-        WasmI32.store(xptr, xlength, 12n)
-        WasmI32.store(yptr, ylength, 12n)
-
-        result
       }
+      WasmI32.store(xptr, xlength, 12n)
+      WasmI32.store(yptr, ylength, 12n)
+
+      return true
     },
     t when t == Tags._GRAIN_ARRAY_HEAP_TAG => {
       let xlength = WasmI32.load(xptr, 4n)
@@ -91,37 +115,37 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
 
       // Check if the same length
       if (xlength != ylength) {
-        false
-      } else if ((xlength & cycleMarker) == cycleMarker) {
-        // Cycle check
-        true
-      } else {
-        WasmI32.store(xptr, xlength ^ cycleMarker, 4n)
-        WasmI32.store(yptr, ylength ^ cycleMarker, 4n)
+        return false
+      }
 
-        let mut result = true
-        let bytes = xlength * 4n
-        for (let mut i = 0n; i < bytes; i += 4n) {
-          if (
-            !equalHelp(WasmI32.load(xptr + i, 8n), WasmI32.load(yptr + i, 8n))
-          ) {
-            result = false
-            break
-          }
-        }
+      // Cycle check
+      if ((xlength & cycleMarker) == cycleMarker) {
+        return true
+      }
 
-        WasmI32.store(xptr, xlength, 4n)
-        WasmI32.store(yptr, ylength, 4n)
+      WasmI32.store(xptr, xlength ^ cycleMarker, 4n)
+      WasmI32.store(yptr, ylength ^ cycleMarker, 4n)
 
-        result
+      let bytes = xlength * 4n
+      for (let mut i = 0n; i < bytes; i += 4n) {
+        if (!equalHelp(WasmI32.load(xptr + i, 8n), WasmI32.load(yptr + i, 8n))) {
+          WasmI32.store(xptr, xlength, 4n)
+          WasmI32.store(yptr, ylength, 4n)
+          return false
+        }
       }
+
+      WasmI32.store(xptr, xlength, 4n)
+      WasmI32.store(yptr, ylength, 4n)
+
+      return true
     },
     t when t == Tags._GRAIN_STRING_HEAP_TAG || t == Tags._GRAIN_BYTES_HEAP_TAG => {
       let xlength = WasmI32.load(xptr, 4n)
       let ylength = WasmI32.load(yptr, 4n)
 
       // Check if the same length
-      if (xlength != ylength) {
+      return if (xlength != ylength) {
         false
       } else {
         Memory.compare(xptr + 8n, yptr + 8n, xlength) == 0n
@@ -132,50 +156,48 @@ let rec heapEqualHelp = (heapTag, xptr, yptr) => {
       let ysize = WasmI32.load(yptr, 4n)
 
       if ((xsize & cycleMarker) == cycleMarker) {
-        true
+        return true
       } else {
         WasmI32.store(xptr, xsize ^ cycleMarker, 4n)
         WasmI32.store(yptr, ysize ^ cycleMarker, 4n)
 
-        let mut result = true
         let bytes = xsize * 4n
         for (let mut i = 0n; i < bytes; i += 4n) {
           if (
             !equalHelp(WasmI32.load(xptr + i, 8n), WasmI32.load(yptr + i, 8n))
           ) {
-            result = false
-            break
+            WasmI32.store(xptr, xsize, 4n)
+            WasmI32.store(yptr, ysize, 4n)
+            return false
           }
         }
 
         WasmI32.store(xptr, xsize, 4n)
         WasmI32.store(yptr, ysize, 4n)
 
-        result
+        return true
       }
     },
     t when t == Tags._GRAIN_UINT32_HEAP_TAG || t == Tags._GRAIN_INT32_HEAP_TAG => {
       let xval = WasmI32.load(xptr, 4n)
       let yval = WasmI32.load(yptr, 4n)
-      xval == yval
+      return xval == yval
     },
     // Float32 is handled by equalHelp directly
     t when t == Tags._GRAIN_UINT64_HEAP_TAG => {
       use WasmI64.{ (==) }
       let xval = WasmI64.load(xptr, 8n)
       let yval = WasmI64.load(yptr, 8n)
-      xval == yval
-    },
-    _ => {
-      // No other implementation
-      xptr == yptr
+      return xval == yval
     },
+    // No other implementation
+    _ => return xptr == yptr,
   }
 }
 and equalHelp = (x, y) => {
   if (
-    (x & Tags._GRAIN_GENERIC_TAG_MASK) != 0n &&
-    (y & Tags._GRAIN_GENERIC_TAG_MASK) != 0n
+    (x & Tags._GRAIN_GENERIC_TAG_MASK) != 0n
+    && (y & Tags._GRAIN_GENERIC_TAG_MASK) != 0n
   ) {
     // Short circuit for non-pointer values
     x == y

package/runtime/equal.md

@@ -14,7 +14,7 @@ No other changes yet.
 </details>
 
 ```grain
-equal : (value1: a, value2: a) => Bool
+equal: (value1: a, value2: a) => Bool
 ```
 
 Check that two values are equal. This checks for structural equality,
@@ -22,14 +22,14 @@ so it also works for comparing things like tuples and lists.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`value1`|`a`|The first operand|
-|`value2`|`a`|The second operand|
+| param    | type | description        |
+| -------- | ---- | ------------------ |
+| `value1` | `a`  | The first operand  |
+| `value2` | `a`  | The second operand |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Bool`|`true` if the values are structurally equal or `false` otherwise|
+| type   | description                                                      |
+| ------ | ---------------------------------------------------------------- |
+| `Bool` | `true` if the values are structurally equal or `false` otherwise |
 

package/runtime/exception.gr

@@ -1,96 +1,76 @@
-@runtimeMode
+@noPervasives
+// Prevent this module from depending on itself
+@noExceptions
 module Exception
 
-from "runtime/unsafe/wasmi32" include WasmI32
-use WasmI32.{ (==), (+), (-) }
-
-foreign wasm fd_write:
-  (WasmI32, WasmI32, WasmI32, WasmI32) => WasmI32 from "wasi_snapshot_preview1"
-
-primitive unreachable = "@unreachable"
-
-provide let mut printers = 0n
-
-// These functions are dangerous because they leak runtime memory and perform
-// no GC operations. As such, they should only be called by this module and/or
-// modules that understand these restrictions, namely Pervasives.
-
-provide let dangerouslyRegisterBasePrinter = f => {
-  let mut current = printers
-  while (true) {
-    // There will be at least one printer registered by the time this is called
-    let (_, next) = WasmI32.toGrain(current):
-      (Exception => Option<String>, WasmI32)
-    if (next == 0n) {
-      // Using a tuple in runtime mode is typically disallowed as there is no way
-      // to reclaim the memory, but this function is only called once
-      let newBase = (WasmI32.fromGrain(f), 0n)
-      WasmI32.store(current, WasmI32.fromGrain(newBase), 12n)
-      break
-    }
-    current = next
-  }
-  // We don't decRef the closure or arguments here to avoid a cyclic dep. on Memory.
-  // This is fine, as this function should only be called once.
-  void
-}
-
-provide let dangerouslyRegisterPrinter = f => {
-  printers = WasmI32.fromGrain((f, printers))
-  // We don't decRef the closure or arguments here to avoid a cyclic dep. on Memory.
-  // This is fine, as this function is only called seldomly.
-  void
-}
-
-// avoid cirular dependency on gc
-let incRef = v => {
-  let ptr = WasmI32.fromGrain(v) - 8n
-  WasmI32.store(ptr, WasmI32.load(ptr, 0n) + 1n, 0n)
-  v
-}
+from "runtime/unsafe/panic" include Panic
 
 let _GENERIC_EXCEPTION_NAME = "GrainException"
-
-let exceptionToString = (e: Exception) => {
-  let mut result = _GENERIC_EXCEPTION_NAME
-  let mut current = printers
-  while (true) {
-    if (current == 0n) return result
-    let (printer, next) = WasmI32.toGrain(current):
-      (Exception => Option<String>, WasmI32)
-    // as GC is not available, manually increment the references
-    match (incRef(printer)(incRef(e))) {
-      Some(str) => return str,
-      None => {
-        current = next
+let mut basePrinter = None
+let mut printers = []
+
+/**
+ * Registers a base exception printer. If no other exception printers are
+ * registered, the base printer is used to convert an exception to a string.
+ *
+ * @param printer: The base exception printer to register
+ *
+ * @since v0.7.0
+ */
+provide let registerBasePrinter = (printer: Exception => String) =>
+  basePrinter = Some(printer)
+
+/**
+ * Registers an exception printer. When an exception is thrown, all registered
+ * printers are called in order from the most recently registered printer to
+ * the least recently registered printer. The first `Some` value returned is
+ * used as the exception's string value.
+ *
+ * @param printer: The exception printer to register
+ *
+ * @since v0.7.0
+ */
+provide let registerPrinter = (printer: Exception => Option<String>) =>
+  printers = [printer, ...printers]
+
+/**
+ * Gets the string representation of the given exception.
+ *
+ * @param e: The exception to stringify
+ *
+ * @returns The string representation of the exception
+ *
+ * @since v0.7.0
+ */
+provide let toString = (e: Exception) => {
+  let rec exceptionToString = (e, printers) => {
+    match (printers) {
+      [] => match (basePrinter) {
+        Some(f) => f(e),
+        None => _GENERIC_EXCEPTION_NAME,
+      },
+      [printer, ...rest] => {
+        match (printer(e)) {
+          Some(s) => s,
+          None => exceptionToString(e, rest),
+        }
       },
     }
   }
-  return result
-}
-
-// HACK: Allocate static buffer for printing (40 bytes)
-// Would be nice to have a better way to allocate a static block from
-// the runtime heap, but this is the only module that needs to do it
-let iov = WasmI32.fromGrain([> 0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n])
-
-provide let panic = (msg: String) => {
-  let ptr = WasmI32.fromGrain(msg)
-  let written = iov + 32n
-  let lf = iov + 36n
-  WasmI32.store(iov, ptr + 8n, 0n)
-  WasmI32.store(iov, WasmI32.load(ptr, 4n), 4n)
-  WasmI32.store8(lf, 10n, 0n)
-  WasmI32.store(iov, lf, 8n)
-  WasmI32.store(iov, 1n, 12n)
-  fd_write(2n, iov, 2n, written)
-  unreachable()
+  exceptionToString(e, printers)
 }
 
+/**
+ * Throws an uncatchable exception and traps.
+ *
+ * @param e: The exception to throw
+ */
 provide let panicWithException = (e: Exception) => {
-  panic(exceptionToString(e))
+  Panic.panic(toString(e))
 }
 
+// Runtime exceptions
+
 provide exception DivisionByZero
 provide exception ModuloByZero
 provide exception Overflow
@@ -126,4 +106,4 @@ let runtimeErrorPrinter = e => {
   }
 }
 
-dangerouslyRegisterPrinter(runtimeErrorPrinter)
+registerPrinter(runtimeErrorPrinter)

package/runtime/exception.md

@@ -6,33 +6,84 @@ title: Exception
 
 Functions and constants included in the Exception module.
 
-### Exception.**printers**
+### Exception.**registerBasePrinter**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
 
 ```grain
-printers : WasmI32
+registerBasePrinter: (printer: (Exception => String)) => Void
 ```
 
-### Exception.**dangerouslyRegisterBasePrinter**
+Registers a base exception printer. If no other exception printers are
+registered, the base printer is used to convert an exception to a string.
 
-```grain
-dangerouslyRegisterBasePrinter : (f: a) => Void
-```
+Parameters:
+
+| param     | type                  | description                            |
+| --------- | --------------------- | -------------------------------------- |
+| `printer` | `Exception => String` | The base exception printer to register |
+
+### Exception.**registerPrinter**
 
-### Exception.**dangerouslyRegisterPrinter**
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
 
 ```grain
-dangerouslyRegisterPrinter : (f: a) => Void
+registerPrinter: (printer: (Exception => Option<String>)) => Void
 ```
 
-### Exception.**panic**
+Registers an exception printer. When an exception is thrown, all registered
+printers are called in order from the most recently registered printer to
+the least recently registered printer. The first `Some` value returned is
+used as the exception's string value.
+
+Parameters:
+
+| param     | type                          | description                       |
+| --------- | ----------------------------- | --------------------------------- |
+| `printer` | `Exception => Option<String>` | The exception printer to register |
+
+### Exception.**toString**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
 
 ```grain
-panic : (msg: String) => a
+toString: (e: Exception) => String
 ```
 
+Gets the string representation of the given exception.
+
+Parameters:
+
+| param | type        | description                |
+| ----- | ----------- | -------------------------- |
+| `e`   | `Exception` | The exception to stringify |
+
+Returns:
+
+| type     | description                                |
+| -------- | ------------------------------------------ |
+| `String` | The string representation of the exception |
+
 ### Exception.**panicWithException**
 
 ```grain
-panicWithException : (e: Exception) => a
+panicWithException: (e: Exception) => a
 ```
 
+Throws an uncatchable exception and traps.
+
+Parameters:
+
+| param | type        | description            |
+| ----- | ----------- | ---------------------- |
+| `e`   | `Exception` | The exception to throw |
+