From fde7a1311543badd1052a757d1e2c68272be1188 Mon Sep 17 00:00:00 2001
From: JJ
Date: Tue, 2 Jan 2024 13:49:25 -0800
Subject: std: more fleshing out. merge std.magic back into std.prelude.

---
 std/hashes.pk           |  4 +++
 std/magic/arrays.pk     | 20 -------------
 std/magic/booleans.pk   | 42 ---------------------------
 std/magic/numbers.pk    | 77 -------------------------------------------------
 std/magic/pointers.pk   |  7 -----
 std/math.pk             |  1 +
 std/net.pk              |  1 +
 std/os.pk               | 10 +++++++
 std/prelude/arrays.pk   | 20 +++++++++++++
 std/prelude/booleans.pk | 42 +++++++++++++++++++++++++++
 std/prelude/debug.pk    | 32 ++++++++++++++++++++
 std/prelude/io.pk       | 21 ++++++++++++--
 std/prelude/numbers.pk  | 77 +++++++++++++++++++++++++++++++++++++++++++++++++
 std/prelude/pointers.pk |  7 +++++
 std/prelude/results.pk  |  2 +-
 std/prelude/strings.pk  |  3 +-
 std/rand.pk             |  1 +
 std/threads.pk          |  1 +
 18 files changed, 218 insertions(+), 150 deletions(-)
 create mode 100644 std/hashes.pk
 delete mode 100644 std/magic/arrays.pk
 delete mode 100644 std/magic/booleans.pk
 delete mode 100644 std/magic/numbers.pk
 delete mode 100644 std/magic/pointers.pk
 create mode 100644 std/math.pk
 create mode 100644 std/net.pk
 create mode 100644 std/os.pk
 create mode 100644 std/prelude/arrays.pk
 create mode 100644 std/prelude/booleans.pk
 create mode 100644 std/prelude/debug.pk
 create mode 100644 std/prelude/numbers.pk
 create mode 100644 std/prelude/pointers.pk
 create mode 100644 std/rand.pk
 create mode 100644 std/threads.pk

diff --git a/std/hashes.pk b/std/hashes.pk
new file mode 100644
index 0000000..911c9d2
--- /dev/null
+++ b/std/hashes.pk
@@ -0,0 +1,4 @@
+## std.hashes: Hash functions on types.
+
+pub type Hash[H] = interface
+  hash[H](Self): H
diff --git a/std/magic/arrays.pk b/std/magic/arrays.pk
deleted file mode 100644
index a0207c1..0000000
--- a/std/magic/arrays.pk
+++ /dev/null
@@ -1,20 +0,0 @@
-## std.arrays: The array[T, S] primitive and associated functions.
-## A stub module for documentation.
-
-## Primitive fixed-size arrays. Their size is statically known at compile-time.
-pub type array[T, S: static[uint]]
-
-## Array access. Returns None if i is out of range.
-pub func get[T, S: static[uint]](self: array[T, S], i: uint): T?
-## Array mutation.
-# todo: how do we detect range errors?
-pub func set[T, S: static[uint]](self: mut array[T, S], i: uint, val: T): T?
-## A helper function to get the length of an array.
-## Known to the compiler, and computed at compile-time.
-pub func len[T, S: static[uint]](self: array[T, S], i: uint): T?
-
-type ArrayIter[T, S: static[uint]] = struct
-  ...
-pub func iter[T, S: static[uint]](self: array[T, S]): ArrayIter[T, S]
-
-# todo: Eq, PartialEq, Ord, PartialOrd
diff --git a/std/magic/booleans.pk b/std/magic/booleans.pk
deleted file mode 100644
index 3c7e28e..0000000
--- a/std/magic/booleans.pk
+++ /dev/null
@@ -1,42 +0,0 @@
-## std.booleans: Booleans and related types. Mostly compiler magic.
-## A stub module for documentation.
-
-pub type unit = union[sole]
-pub type bool = union[false, true]
-
-# note: puck could resolve kleene.false vs bool.false...
-# this is probably not worth it compared to improved type inference
-# pub type Kleene = union[False, Maybe, True]
-
-## Boolean equality
-pub func ==(a: bool, b: bool): bool =
-  match a
-  of (true, true), (false, false): true
-  of (false, true), (true, false): false
-
-pub func !=(a: bool, b: bool): bool =
-  not a == b
-
-## Boolean negation
-pub func not(a: bool): bool =
-  match a
-  of true: false
-  of false: true
-
-## Boolean conjunction
-pub func and(a: bool, b: bool): bool =
-  match (a, b)
-  of (true, true): true
-  of _: false
-
-## Boolean disjunction
-pub func or(a: bool, b: bool): bool =
-  match (a, b)
-  of (false, false): false
-  of _: true
-
-## Boolean exclusive disjunction
-pub func xor(a: bool, b: bool): bool =
-  match (a, b)
-  of (true, true), (false, false): false
-  of (true, false), (false, true): true
diff --git a/std/magic/numbers.pk b/std/magic/numbers.pk
deleted file mode 100644
index 007f4b7..0000000
--- a/std/magic/numbers.pk
+++ /dev/null
@@ -1,77 +0,0 @@
-## std.numbers: Operations on numbers and such.
-## A stub module for documentation.
-# reference: https://en.wikipedia.org/wiki/IEEE_754
-
-## The default integer type. Size depends on architecture.
-pub type int
-## A signed 8-bit integer.
-pub type i8
-## A signed 16-bit integer.
-pub type i16
-## A signed 32-bit integer.
-pub type i32
-## A signed 64-bit integer.
-pub type i64
-## A signed 128-bit integer.
-pub type i128
-
-## The default unsigned integer type. Size depends on architecture.
-pub type uint
-## An unsigned 8-bit integer.
-pub type u8
-## An unsigned 16-bit integer.
-pub type u16
-## An unsigned 32-bit integer.
-pub type u32
-## An unsigned 64-bit integer.
-pub type u64
-## An unsigned 128-bit integer.
-pub type u128
-
-## A floating-point type. Takes up 64 bits by default.
-pub type float = f64
-## A 32-bit floating point type. Single precision.
-pub type f32
-## A 64-bit floating point type. Double precision.
-pub type f64
-## A 128-bit floating point type. Quadruple precision.
-pub type f128
-
-## A decimal type, according to IEEE 754. Takes up 64 bits by default.
-pub type decimal = dec64
-## A 64-bit decimal type.
-pub type dec64
-## A 128-bit decimal type.
-pub type dec128
-
-## 8-bit bytes.
-pub type byte = u8
-## 4-byte chars. These represent distinct Unicode characters.
-pub type char = distinct u32
-## An alias to `char`, to match with `str`.
-pub type chr = char
-
-## The IEEE floating point value of *Not a Number*.
-pub const NaN: f64 = 0x7FF7FFFFFFFFFFFF
-## The IEEE floating point value of positive infinity.
-pub const Inf: f64 = 0x7FF0000000000000
-## The IEEE floating point value of negative infinity.
-pub const NegInf: f64 = 0xFFF0000000000000
-
-# todo: type conversions
-
-pub func +[T](a: T, b: T): T
-pub func -[T](a: T, b: T): T
-pub func *[T](a: T, b: T): T
-pub func /[T](a: T, b: T): float
-pub func ^[T](a: T, b: T): T # todo: should be exp?
-
-pub func div[T](a: T, b: T): T
-pub func mod[T](a: T, b: T): T # fixme
-pub func rem[T](a: T, b: T): T
-
-pub func shl[T](a: T): T
-pub func shr[T](a: T): T
-
-pub func abs[T](a: T): T
-pub func neg[T](a: T): bool
diff --git a/std/magic/pointers.pk b/std/magic/pointers.pk
deleted file mode 100644
index e2a95cf..0000000
--- a/std/magic/pointers.pk
+++ /dev/null
@@ -1,7 +0,0 @@
-## std.pointers: Pointer arithmetic. Unsafe.
-
-pub type ptr[T]
-pub type ref[T]
-pub type unique[T]
-
-# idk what goes here
diff --git a/std/math.pk b/std/math.pk
new file mode 100644
index 0000000..e62f3c4
--- /dev/null
+++ b/std/math.pk
@@ -0,0 +1 @@
+## std.math: Utility types and functions for basic mathematics.
diff --git a/std/net.pk b/std/net.pk
new file mode 100644
index 0000000..1c5567c
--- /dev/null
+++ b/std/net.pk
@@ -0,0 +1 @@
+## std.net: A cross-platform implementation of the Sockets API.
diff --git a/std/os.pk b/std/os.pk
new file mode 100644
index 0000000..c28796f
--- /dev/null
+++ b/std/os.pk
@@ -0,0 +1,10 @@
+## std.os: OS-specific functions, as well as some general abstractions.
+
+pub func exit(code: uint = 0): never =
+  ...
+
+pub func sleep(milliseconds: uint) =
+  ...
+
+pub func admin: bool =
+  ...
diff --git a/std/prelude/arrays.pk b/std/prelude/arrays.pk
new file mode 100644
index 0000000..2e4a4d4
--- /dev/null
+++ b/std/prelude/arrays.pk
@@ -0,0 +1,20 @@
+## std.arrays: The array[T, S] primitive and associated functions.
+## A stub module for documentation. Mostly compiler magic.
+
+## Primitive fixed-size arrays. Their size is statically known at compile-time.
+pub type array[T, S: static[uint]]
+
+## Array access. Returns None if i is out of range.
+pub func get[T, S: static[uint]](self: array[T, S], i: uint): T?
+## Array mutation.
+# todo: how do we detect range errors?
+pub func set[T, S: static[uint]](self: mut array[T, S], i: uint, val: T): T?
+## A helper function to get the length of an array.
+## Known to the compiler, and computed at compile-time.
+pub func len[T, S: static[uint]](self: array[T, S], i: uint): T?
+
+type ArrayIter[T, S: static[uint]] = struct
+  ...
+pub func iter[T, S: static[uint]](self: array[T, S]): ArrayIter[T, S]
+
+# todo: Eq, PartialEq, Ord, PartialOrd
diff --git a/std/prelude/booleans.pk b/std/prelude/booleans.pk
new file mode 100644
index 0000000..bd81925
--- /dev/null
+++ b/std/prelude/booleans.pk
@@ -0,0 +1,42 @@
+## std.booleans: Booleans and related types. Mostly compiler magic.
+## A stub module for documentation. Mostly compiler magic.
+
+pub type unit = union[sole]
+pub type bool = union[false, true]
+
+# note: puck could resolve kleene.false vs bool.false...
+# this is probably not worth it compared to improved type inference
+# pub type Kleene = union[False, Maybe, True]
+
+## Boolean equality
+pub func ==(a: bool, b: bool): bool =
+  match a
+  of (true, true), (false, false): true
+  of (false, true), (true, false): false
+
+pub func !=(a: bool, b: bool): bool =
+  not a == b
+
+## Boolean negation
+pub func not(a: bool): bool =
+  match a
+  of true: false
+  of false: true
+
+## Boolean conjunction
+pub func and(a: bool, b: bool): bool =
+  match (a, b)
+  of (true, true): true
+  of _: false
+
+## Boolean disjunction
+pub func or(a: bool, b: bool): bool =
+  match (a, b)
+  of (false, false): false
+  of _: true
+
+## Boolean exclusive disjunction
+pub func xor(a: bool, b: bool): bool =
+  match (a, b)
+  of (true, true), (false, false): false
+  of (true, false), (false, true): true
diff --git a/std/prelude/debug.pk b/std/prelude/debug.pk
new file mode 100644
index 0000000..3af1def
--- /dev/null
+++ b/std/prelude/debug.pk
@@ -0,0 +1,32 @@
+## std.debug: Useful functions for debugging.
+## This module is imported by default.
+
+## The special ... syntax is used to mark unimplemented parts of code.
+## Such code will compile, but panic upon being called at runtime.
+## It is usable almost anywhere, including in type declarations, thanks to compiler magic.
+pub func ...: never
+
+## The `assert` macro checks that a provided assertation is true,
+## and panics and dumps information if it is not.
+## Asserts remain in release builds. If not desired, see `debug_assert`
+pub macro assert(cond: bool) =
+  quote:
+    if not `cond`:
+      panic "assertation failed!\n {}".fmt(dbg(`cond`))
+
+## The `debug_assert` function provides an assert that is compiled out in release builds.
+## This is useful for debugging performance-critical code.
+pub macro debug_assert(cond: bool)
+  quote:
+    when debug: # fixme: where is this coming from?
+      assert `cond`
+
+## The `discard` function consumes any type.
+## Useful for throwing away the result of a computation.
+pub func discard[T](self: T) =
+  return
+
+## The `panic` function prints a message to `stderr` and quits.
+pub func panic(message: str): never =
+  stderr.write(message, "\n")
+  std.os.exit(1)
diff --git a/std/prelude/io.pk b/std/prelude/io.pk
index e621e01..7a3f059 100644
--- a/std/prelude/io.pk
+++ b/std/prelude/io.pk
@@ -1,5 +1,7 @@
-## std.io: Platform-independent I/O constructs.
+## std.io: Platform-independent I/O constructs. Mostly revolve around files.
 ## This module is imported by default.
+# reference: https://nim-lang.org/docs/syncio.html
+# reference: https://doc.rust-lang.org/stable/std/io/
 
 pub type File = ...
 pub type FileMode = union[Read, Write, ReadWrite, Append]
@@ -13,7 +15,7 @@ pub const stderr: File = ...
 pub func open(path: str, mode: FileMode): File =
   ...
 
-pub func close(file: File) =
+pub func close(file: owned File) =
   ...
 
 pub func write(file: File, values: varargs[str]) =
@@ -27,3 +29,18 @@ pub func lines(file: File): Iter[str] =
 
 pub func chars(file: File): Iter[chr] =
   ...
+
+pub func exists(file: File): bool =
+  ...
+
+pub func hidden(file: File): bool =
+  ...
+
+pub func size(file: File): uint =
+  ...
+
+pub func dir(file: File): str =
+  ...
+
+pub func path(file: File): str =
+  ...
diff --git a/std/prelude/numbers.pk b/std/prelude/numbers.pk
new file mode 100644
index 0000000..7857d34
--- /dev/null
+++ b/std/prelude/numbers.pk
@@ -0,0 +1,77 @@
+## std.numbers: Operations on numbers and such.
+## A stub module for documentation. Mostly compiler magic.
+# reference: https://en.wikipedia.org/wiki/IEEE_754
+
+## The default integer type. Size depends on architecture.
+pub type int
+## A signed 8-bit integer.
+pub type i8
+## A signed 16-bit integer.
+pub type i16
+## A signed 32-bit integer.
+pub type i32
+## A signed 64-bit integer.
+pub type i64
+## A signed 128-bit integer.
+pub type i128
+
+## The default unsigned integer type. Size depends on architecture.
+pub type uint
+## An unsigned 8-bit integer.
+pub type u8
+## An unsigned 16-bit integer.
+pub type u16
+## An unsigned 32-bit integer.
+pub type u32
+## An unsigned 64-bit integer.
+pub type u64
+## An unsigned 128-bit integer.
+pub type u128
+
+## A floating-point type. Takes up 64 bits by default.
+pub type float = f64
+## A 32-bit floating point type. Single precision.
+pub type f32
+## A 64-bit floating point type. Double precision.
+pub type f64
+## A 128-bit floating point type. Quadruple precision.
+pub type f128
+
+## A decimal type, according to IEEE 754. Takes up 64 bits by default.
+pub type decimal = dec64
+## A 64-bit decimal type.
+pub type dec64
+## A 128-bit decimal type.
+pub type dec128
+
+## 8-bit bytes.
+pub type byte = u8
+## 4-byte chars. These represent distinct Unicode characters.
+pub type char = distinct u32
+## An alias to `char`, to match with `str`.
+pub type chr = char
+
+## The IEEE floating point value of *Not a Number*.
+pub const NaN: f64 = 0x7FF7FFFFFFFFFFFF
+## The IEEE floating point value of positive infinity.
+pub const Inf: f64 = 0x7FF0000000000000
+## The IEEE floating point value of negative infinity.
+pub const NegInf: f64 = 0xFFF0000000000000
+
+# todo: type conversions
+
+pub func +[T](a: T, b: T): T
+pub func -[T](a: T, b: T): T
+pub func *[T](a: T, b: T): T
+pub func /[T](a: T, b: T): float
+pub func ^[T](a: T, b: T): T # todo: should be exp?
+
+pub func div[T](a: T, b: T): T
+pub func mod[T](a: T, b: T): T # fixme
+pub func rem[T](a: T, b: T): T
+
+pub func shl[T](a: T): T
+pub func shr[T](a: T): T
+
+pub func abs[T](a: T): T
+pub func neg[T](a: T): bool
diff --git a/std/prelude/pointers.pk b/std/prelude/pointers.pk
new file mode 100644
index 0000000..e2a95cf
--- /dev/null
+++ b/std/prelude/pointers.pk
@@ -0,0 +1,7 @@
+## std.pointers: Pointer arithmetic. Unsafe.
+
+pub type ptr[T]
+pub type ref[T]
+pub type unique[T]
+
+# idk what goes here
diff --git a/std/prelude/results.pk b/std/prelude/results.pk
index 7dc5a11..81bccf0 100644
--- a/std/prelude/results.pk
+++ b/std/prelude/results.pk
@@ -1,7 +1,7 @@
 ## std.results: Result types.
 ## This module is imported by default.
 
-use std[options, format]
+use std.[options, format]
 
 ## The Result type. Represents either success or failure.
 pub type Result[T, E] = union
diff --git a/std/prelude/strings.pk b/std/prelude/strings.pk
index 6abca31..2f48b67 100644
--- a/std/prelude/strings.pk
+++ b/std/prelude/strings.pk
@@ -89,7 +89,7 @@ pub func chars(self: str): list[chr] # todo: useful?
 pub func &(a: str, b: str): str =
   ...
 
-## Syntatic sugar for string appending.
+## Syntactic sugar for string appending.
 pub func &=(a: mut str, b: owned str) =
   a.push(b)
 
@@ -98,3 +98,4 @@ pub func &=(a: mut str, b: owned str) =
 # pub func iter(self: str): StrIter
 # pub func next(self: mut StrIter)
 # pub func peek(self: mut StrIter)
+# pub func peek_nth(self: mut StrIter, i: uint)
diff --git a/std/rand.pk b/std/rand.pk
new file mode 100644
index 0000000..f608a78
--- /dev/null
+++ b/std/rand.pk
@@ -0,0 +1 @@
+## std.rand: Functions for randomness
diff --git a/std/threads.pk b/std/threads.pk
new file mode 100644
index 0000000..2b1e98f
--- /dev/null
+++ b/std/threads.pk
@@ -0,0 +1 @@
+## std.threads: Primitives for threads and thread-safe code.
-- 
cgit v1.2.3-70-g09d2