From 8c97575c8fb93671e4ac51fa8232a1a2cfb7ad22 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Thu, 17 Apr 2025 14:57:09 -0400
Subject: Add getenv()/setenv()

---
 docs/builtins.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 docs/builtins.md

(limited to 'docs/builtins.md')

diff --git a/docs/builtins.md b/docs/builtins.md
new file mode 100644
index 00000000..f1d8069f
--- /dev/null
+++ b/docs/builtins.md
@@ -0,0 +1,184 @@
+# Built-in Functions
+
+These are the top-level functions built into Tomo.
+
+- [`func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Text?)`](#ask)
+- [`func ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)`](#exit)
+- [`func getenv(name:Text -> Text?)`](#getenv)
+- [`func print(text:Text, newline:Bool = yes -> Void)`](#print)
+- [`func say(text:Text, newline:Bool = yes -> Void)`](#say)
+- [`func setenv(name:Text, value:Text)`](#setenv)
+- [`func sleep(seconds: Num -> Void)`](#sleep)
+- [`func fail(message:Text -> Abort)`](#fail)
+
+---
+
+### `ask`
+Gets a line of user input text with a prompt.
+
+```tomo
+func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Text?)
+```
+
+- `prompt`: The text to print as a prompt before getting the input.
+- `bold`: Whether or not to print make the prompt appear bold on a console
+  using the ANSI escape sequence `\x1b[1m`.
+- `force_tty`: When a program is receiving input from a pipe or writing its
+  output to a pipe, this flag (which is enabled by default) forces the program
+  to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which
+  circumvents the pipe. This means that `foo | ./tomo your-program | baz` will
+  still show a visible prompt and read user input, despite the pipes. Setting
+  this flag to `no` will mean that the prompt is written to `stdout` and input
+  is read from `stdin`, even if those are pipes.
+
+**Returns:**  
+A line of user input text without a trailing newline, or empty text if
+something went wrong (e.g. the user hit `Ctrl-D`).
+
+**Example:**  
+```tomo
+>> ask("What's your name? ")
+= "Arthur Dent"
+```
+
+---
+
+### `exit`
+Exits the program with a given status and optionally prints a message.
+
+```tomo
+func exit(message:Text? = !Text, status:Int32 = 1[32] -> Void)
+```
+
+- `message`: If nonempty, this message will be printed (with a newline) before
+  exiting.
+- `status`: The status code that the program with exit with (default: 1, which
+  is a failure status).
+
+**Returns:**  
+This function never returns.
+
+**Example:**  
+```tomo
+exit(status=1, "Goodbye forever!")
+```
+
+---
+
+### `getenv`
+Gets an environment variable.
+
+```tomo
+func getenv(name:Text -> Text?)
+```
+
+- `name`: The name of the environment variable to get.
+
+**Returns:**  
+If set, the environment variable's value, otherwise, `none`.
+
+**Example:**  
+```tomo
+>> getenv("TERM")
+= "xterm-256color"?
+```
+
+---
+
+### `print`
+Prints a message to the console (alias for [`say`](#say)).
+
+```tomo
+func print(text:Text, newline:Bool = yes -> Void)
+```
+
+- `text`: The text to print.
+- `newline`: Whether or not to print a newline after the text.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+print("Hello ", newline=no)
+print("world!")
+```
+
+---
+
+### `say`
+Prints a message to the console.
+
+```tomo
+func say(text:Text, newline:Bool = yes -> Void)
+```
+
+- `text`: The text to print.
+- `newline`: Whether or not to print a newline after the text.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+say("Hello ", newline=no)
+say("world!")
+```
+
+---
+
+### `setenv`
+Sets an environment variable.
+
+```tomo
+func getenv(name:Text, value:Text -> Void)
+```
+
+- `name`: The name of the environment variable to set.
+- `value`: The new value of the environment variable.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+setenv("FOOBAR", "xyz")
+```
+
+---
+
+### `sleep`
+Pause execution for a given number of seconds.
+
+```tomo
+func sleep(seconds: Num -> Void)
+```
+
+- `seconds`: How many seconds to sleep for.
+
+**Returns:**  
+Nothing.
+
+**Example:**  
+```tomo
+sleep(1.5)
+```
+
+---
+
+### `fail`
+Prints a message to the console, aborts the program, and prints a stack trace.
+
+```tomo
+func fail(message:Text -> Abort)
+```
+
+- `message`: The error message to print.
+
+**Returns:**  
+Nothing, aborts the program.
+
+**Example:**  
+```tomo
+fail("Oh no!")
+```
-- 
cgit v1.2.3