fix: update main function docs to reflect default handlers

src/hello-world.md

@@ -13,7 +13,7 @@ You will immediately notice a few things are different from other programming
 languages: 
 
 - The `main` function has no formal parameters, in particular it does not take
-  an arguments array. Instead the command line arguments are available by
-  calling the `Environment.getArgs` functions.
+  an arguments array. Instead the command line arguments are available through
+  the `Env` effect (see [The Main Function](./main.md)).
 - The return type of the `main` function is `Unit`.
 - The `main` function has the `IO` effect since it prints to the terminal.

src/main.md

@@ -1,27 +1,60 @@
 # The Main Function
 
-The entry point of any Flix program is the `main` function which _must_ have the
-signature:
+The entry point of any Flix program is the `main` function which must take zero
+arguments and return `Unit`:
 
 ```flix
-def main(): Unit \ IO
+def main(): Unit \ IO =
+    println("Hello World!")
 ```
 
-That is, the `main` function:
+## Effects of Main
+
+The `main` function can use any combination of:
 
-1. must return `Unit`, and
-2. must be marked as effectful (i.e. have the effect annotation `\ IO`).
+- **Primitive effects:** `IO` and `NonDet`.
+- **Any effect with a default handler:** for example `Env`, `Exit`, `Clock`,
+  `Logger`, and others.
 
-The signature of `main` does not specify any arguments, but the command line
-arguments passed to the program can be accessed by calling
-`Environment.getArgs()`:
+Effects with default handlers are automatically translated into `IO` by the Flix
+compiler. See [Default Handlers](./default-handlers.md) for details.
+
+For example, main can use the `Env` and `Exit` effects:
 
 ```flix
-def main(): Unit \ IO =
-    let args = Environment.getArgs();
-    ...
+def main(): Unit \ {Env, Exit} =
+    let args = Env.getArgs();
+    match List.head(args) {
+        case None    =>
+            println("Missing argument.");
+            Exit.exit(1)
+        case Some(a) =>
+            println("Hello ${a}!")
+    }
 ```
 
-Flix requires `main` to have the `IO` effect. If main was pure there would be no
-reason to run the program. Typically the effectful requirement is satisfied
-because `main` prints to the console or has another side-effect.
+## Accessing Command Line Arguments
+
+The command line arguments passed to the program can be accessed by calling
+`Env.getArgs()` through the `Env` effect:
+
+```flix
+def main(): Unit \ {Env, IO} =
+    let args = Env.getArgs();
+    println("Arguments: ${args}")
+```
+
+## Exiting the Program
+
+The program can be terminated with a specific exit code using `Exit.exit`:
+
+```flix
+def main(): Unit \ Exit =
+    Exit.exit(0)
+```
+
+## Why Must Main Be Effectful?
+
+Flix requires `main` to be effectful. If `main` was pure there would be no
+reason to run the program. Typically this requirement is satisfied because `main`
+prints to the console or has another side-effect.