feat: add Clock, Sleep, Random, Logger, Env, Exit pages

src/SUMMARY.md

@@ -35,9 +35,15 @@
   - [Effect-Oriented Programming](./effect-oriented-programming.md)
 - [Library Effects](./library-effects.md)
   - [Assert](./assert.md)
+  - [Clock](./clock.md)
   - [Console](./console.md)
+  - [Env](./env.md)
+  - [Exit](./exit.md)
   - [Http and Https](./http-and-https.md)
+  - [Logger](./logger.md)
   - [Process](./process.md)
+  - [Random](./random.md)
+  - [Sleep](./sleep.md)
 - [Modules](./modules.md)
   - [Declaring Modules](./declaring-modules.md)
   - [Using Modules](./using-modules.md)

src/clock.md

@@ -0,0 +1,61 @@
+# Clock
+
+Flix provides `Clock` as a library effect for querying the current wall-clock
+time. The `Clock` effect has a default handler, so no explicit `runWithIO` call
+is needed in `main`. The key module is `Time.Clock`.
+
+## The Clock Effect
+
+The `Clock` effect has a single operation that returns the time since the epoch
+in a given unit:
+
+```flix
+pub eff Clock {
+    /// Returns a measure of time since the epoch in the given time unit `u`.
+    def currentTime(u: TimeUnit): Int64
+}
+```
+
+The `TimeUnit` enum determines the granularity of the result:
+
+```flix
+pub enum TimeUnit with Eq, ToString {
+    case Days,
+    case Hours,
+    case Microseconds,
+    case Milliseconds,
+    case Minutes,
+    case Nanoseconds,
+    case Seconds
+}
+```
+
+## Reading the Current Time
+
+The simplest use of `Clock` is to read the current time and print it:
+
+```flix
+use Time.Clock
+use Time.TimeUnit
+
+def main(): Unit \ { Clock, IO } =
+    let timestamp = Clock.currentTime(TimeUnit.Milliseconds);
+    println("${timestamp} ms since the epoch")
+```
+
+Because `Clock` has a default handler, the effect is handled automatically.
+
+## The `now` Function
+
+The `Clock.now` function is a shorthand for
+`Clock.currentTime(TimeUnit.Milliseconds)`:
+
+```flix
+use Time.Clock
+
+def main(): Unit \ { Clock, IO } =
+    let before = Clock.now();
+    // ... do some work ...
+    let after = Clock.now();
+    println("Elapsed: ${after - before} ms")
+```

src/env.md

@@ -0,0 +1,110 @@
+# Env
+
+Flix provides `Env` as a library effect for accessing environment variables,
+system properties, and platform information. The `Env` effect has a default
+handler, so no explicit `runWithIO` call is needed in `main`. The key module is
+`Sys.Env`.
+
+## The Env Effect
+
+The `Env` effect provides operations for reading the program's environment:
+
+```flix
+pub eff Env {
+    /// Returns the arguments passed to the program via the command line.
+    def getArgs(): List[String]
+
+    /// Returns a map of the current system environment.
+    def getEnv(): Map[String, String]
+
+    /// Returns the value of the specified environment variable.
+    def getVar(name: String): Option[String]
+
+    /// Returns the system property by name.
+    def getProp(name: String): Option[String]
+
+    /// Returns the operating system name.
+    def getOsName(): Option[String]
+
+    /// Returns the operating system architecture.
+    def getOsArch(): Option[String]
+
+    /// Returns the operating system version.
+    def getOsVersion(): Option[String]
+
+    /// Returns the file separator.
+    def getFileSeparator(): String
+
+    /// Returns the path separator.
+    def getPathSeparator(): String
+
+    /// Returns the system line separator.
+    def getLineSeparator(): String
+
+    /// Returns the user's current working directory.
+    def getCurrentWorkingDirectory(): Option[String]
+
+    /// Returns the default temp file path.
+    def getTemporaryDirectory(): Option[String]
+
+    /// Returns the user's account name.
+    def getUserName(): Option[String]
+
+    /// Returns the user's home directory.
+    def getUserHomeDirectory(): Option[String]
+
+    /// Returns the number of virtual processors available to the JVM.
+    def getVirtualProcessors(): Int32
+}
+```
+
+## Directories and OS Info
+
+The simplest use of `Env` is to query the current directory, home directory,
+or operating system:
+
+```flix
+use Sys.Env
+
+def main(): Unit \ { Env, IO } =
+    let home = Env.getUserHomeDirectory();
+    println("Home: ${home}");
+    let cwd = Env.getCurrentWorkingDirectory();
+    println("CWD: ${cwd}");
+    let os = Env.getOsName();
+    println("OS: ${os}")
+```
+
+## Environment Variables
+
+Use `getVar` to read a single environment variable, or `getEnv` to retrieve all
+of them as a map:
+
+```flix
+use Sys.Env
+
+def main(): Unit \ { Env, IO } =
+    let path = Env.getVar("PATH");
+    println("PATH: ${path}");
+    let all = Env.getEnv();
+    println("Total env vars: ${Map.size(all)}")
+```
+
+## System Information
+
+The `Env` effect also exposes platform details such as the OS architecture and
+the number of available processors:
+
+```flix
+use Sys.Env
+
+def main(): Unit \ { Env, IO } =
+    let name    = Env.getOsName();
+    let arch    = Env.getOsArch();
+    let version = Env.getOsVersion();
+    let cpus    = Env.getVirtualProcessors();
+    println("OS:   ${name}");
+    println("Arch: ${arch}");
+    println("Ver:  ${version}");
+    println("CPUs: ${cpus}")
+```

src/exit.md

@@ -0,0 +1,34 @@
+# Exit
+
+Flix provides `Exit` as a library effect for terminating the program. The `Exit`
+effect has a default handler, so no explicit `runWithIO` call is needed in
+`main`. The key module is `Sys.Exit`.
+
+## The Exit Effect
+
+The `Exit` effect has a single operation that immediately stops the JVM with a
+given exit code:
+
+```flix
+pub eff Exit {
+    /// Immediately exits the JVM with the specified `exitCode`.
+    def exit(exitCode: Int32): Void
+}
+```
+
+The return type `Void` indicates that `exit` never returns normally.
+
+## Exiting the Program
+
+The simplest use of `Exit` is to terminate with a specific exit code:
+
+```flix
+use Sys.Exit
+
+def main(): Unit \ { Exit, IO } =
+    println("Goodbye!");
+    Exit.exit(0)
+```
+
+A zero exit code conventionally signals success, while a non-zero code signals
+an error.

src/library-effects.md

@@ -4,9 +4,15 @@ Flix provides several built-in library effects for common I/O operations. These
 effects all have default handlers, so no explicit `runWithIO` is needed in
 `main`.
 
-| Effect                          | Module                    | Description                                                                                      |
-|---------------------------------|---------------------------|--------------------------------------------------------------------------------------------------|
-| [Assert](./assert.md)           | `Assert`                  | Runtime assertions (`assertTrue`, `assertEq`, etc.) with configurable handlers.                  |
-| [Console](./console.md)         | `Sys.Console`             | Terminal I/O: reading input, printing to stdout/stderr, prompts, and menus.                      |
-| [Http / Https](./http-https.md) | `Net.Http`, `Net.Https`   | Sending HTTP requests with a fluent API, middleware (retries, rate limiting, circuit breakers).   |
-| [Process](./process.md)         | `Sys.Process`             | Spawning and managing OS processes.                                                              |
+| Effect                                              | Description                                                                                    |
+|------------------------------------------------------|------------------------------------------------------------------------------------------------|
+| [`Assert`](./assert.md)                              | Runtime assertions (`assertTrue`, `assertEq`, etc.) with configurable handlers.                |
+| [`Logger`](./logger.md)                              | Structured logging at five severity levels with filtering and collection.                      |
+| [`Math.Random`](./random.md)                         | Generating pseudorandom numbers, with optional seeded determinism.                             |
+| [`Net.Http` / `Net.Https`](./http-and-https.md)      | Sending HTTP requests with a fluent API, middleware (retries, rate limiting, circuit breakers). |
+| [`Sys.Console`](./console.md)                        | Terminal I/O: reading input, printing to stdout/stderr, prompts, and menus.                    |
+| [`Sys.Env`](./env.md)                                | Accessing environment variables, system properties, and platform information.                  |
+| [`Sys.Exit`](./exit.md)                              | Terminating the program with a specific exit code.                                             |
+| [`Sys.Process`](./process.md)                        | Spawning and managing OS processes.                                                            |
+| [`Time.Clock`](./clock.md)                           | Querying the current wall-clock time in various units.                                         |
+| [`Time.Sleep`](./sleep.md)                           | Pausing the current thread with composable middleware (jitter, caps, logging).                  |

src/logger.md

@@ -0,0 +1,72 @@
+# Logger
+
+Flix provides `Logger` as a library effect for structured logging. The `Logger`
+effect has a default handler, so no explicit `runWithIO` call is needed in
+`main`. The key module is `Logger`.
+
+## The Logger Effect
+
+The `Logger` effect has a single operation that logs a message at a given
+severity:
+
+```flix
+pub eff Logger {
+    /// Logs the given message `m` at the given severity `s`.
+    def log(s: Severity, m: RichString): Unit
+}
+```
+
+The `Severity` enum defines five levels, from lowest to highest:
+
+```flix
+pub enum Severity with Eq, Order, ToString {
+    case Trace
+    case Debug
+    case Info
+    case Warn
+    case Fatal
+}
+```
+
+## The Logger Module
+
+The `Logger` module provides convenience functions:
+
+```flix
+mod Logger {
+    /// Logs the message `m` at the Trace level.
+    def trace(m: a): Unit \ Logger with Formattable[a]
+
+    /// Logs the message `m` at the Debug level.
+    def debug(m: a): Unit \ Logger with Formattable[a]
+
+    /// Logs the message `m` at the Info level.
+    def info(m: a): Unit \ Logger with Formattable[a]
+
+    /// Logs the message `m` at the Warn level.
+    def warn(m: a): Unit \ Logger with Formattable[a]
+
+    /// Logs the message `m` at the Fatal level.
+    def fatal(m: a): Unit \ Logger with Formattable[a]
+```
+
+> **Note:** The logging functions accept any type that implements the
+> `Formattable` trait. Most standard types (`String`, `Int32`, `Bool`, etc.)
+> implement `Formattable`, so plain values can be logged directly. The trait
+> converts values into `RichString`, which supports styled terminal output
+> (colors, bold, etc.).
+
+## Logging Messages
+
+The convenience functions accept any value that implements `Formattable`:
+
+```flix
+def main(): Unit \ { Logger } =
+    Logger.info("Application started");
+    Logger.debug("Loading configuration...");
+    Logger.warn("Cache size exceeds threshold");
+    Logger.fatal("Unrecoverable error")
+```
+
+The default handler prints each message to standard output with a colored
+severity prefix, for example: `[Info] Application started`.