From 2a24b0a3fc3c4986572ae2c4ea0e8e387497a7f6 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 23 Nov 2025 14:19:04 -0500
Subject: Add `at_cleanup()` function

---
 api/api.md        | 26 +++++++++++++++++++++++++-
 api/builtins.md   | 26 +++++++++++++++++++++++++-
 api/builtins.yaml | 28 +++++++++++++++++++++++++++-
 3 files changed, 77 insertions(+), 3 deletions(-)

(limited to 'api')

diff --git a/api/api.md b/api/api.md
index 02ad054e..5c9dc9c4 100644
--- a/api/api.md
+++ b/api/api.md
@@ -32,11 +32,35 @@ force_tty | `Bool` | Whether or not to force the use of /dev/tty.  | `yes`
 ```tomo
 assert ask("What's your name? ") == "Arthur Dent"
 
+```
+## at_cleanup
+
+```tomo
+at_cleanup : func(fn: func() -> Void)
+```
+
+Register a function that runs at cleanup time for Tomo programs. Cleanup time happens when a program exits (see `atexit()` in C), or immediately before printing error messages in a call to `fail()`. This allows for terminal cleanup so error messages can be visible as the program shuts down.
+
+Use this API very carefully, because errors that occur during cleanup functions may make it extremely hard to figure out what's going on. Cleanup functions should be designed to not error under any circumstances.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+fn | `func()` | A function to run at cleanup time.  | -
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+at_cleanup(func()
+    (/tmp/file.txt).remove(ignore_missing=yes)
+)
+
 ```
 ## exit
 
 ```tomo
-exit : func(message: Text? = none, status: Int32 = Int32(1) -> Void)
+exit : func(message: Text? = none, status: Int32 = Int32(1) -> Abort)
 ```
 
 Exits the program with a given status and optionally prints a message.
diff --git a/api/builtins.md b/api/builtins.md
index 0b06a41b..6d042741 100644
--- a/api/builtins.md
+++ b/api/builtins.md
@@ -32,11 +32,35 @@ force_tty | `Bool` | Whether or not to force the use of /dev/tty.  | `yes`
 ```tomo
 assert ask("What's your name? ") == "Arthur Dent"
 
+```
+## at_cleanup
+
+```tomo
+at_cleanup : func(fn: func() -> Void)
+```
+
+Register a function that runs at cleanup time for Tomo programs. Cleanup time happens when a program exits (see `atexit()` in C), or immediately before printing error messages in a call to `fail()`. This allows for terminal cleanup so error messages can be visible as the program shuts down.
+
+Use this API very carefully, because errors that occur during cleanup functions may make it extremely hard to figure out what's going on. Cleanup functions should be designed to not error under any circumstances.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+fn | `func()` | A function to run at cleanup time.  | -
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+at_cleanup(func()
+    (/tmp/file.txt).remove(ignore_missing=yes)
+)
+
 ```
 ## exit
 
 ```tomo
-exit : func(message: Text? = none, status: Int32 = Int32(1) -> Void)
+exit : func(message: Text? = none, status: Int32 = Int32(1) -> Abort)
 ```
 
 Exits the program with a given status and optionally prints a message.
diff --git a/api/builtins.yaml b/api/builtins.yaml
index 2eae5340..764a1bd4 100644
--- a/api/builtins.yaml
+++ b/api/builtins.yaml
@@ -38,7 +38,7 @@ exit:
   description: >
     Exits the program with a given status and optionally prints a message.
   return:
-    type: 'Void'
+    type: 'Abort'
     description: >
       This function never returns.
   args:
@@ -56,6 +56,32 @@ exit:
   example: |
     exit(status=1, "Goodbye forever!")
 
+at_cleanup:
+  short: register a cleanup function
+  description: >
+    Register a function that runs at cleanup time for Tomo programs. Cleanup
+    time happens when a program exits (see `atexit()` in C), or immediately
+    before printing error messages in a call to `fail()`. This allows for
+    terminal cleanup so error messages can be visible as the program shuts
+    down.
+  note: >
+    Use this API very carefully, because errors that occur during cleanup
+    functions may make it extremely hard to figure out what's going on. Cleanup
+    functions should be designed to not error under any circumstances.
+  args:
+    fn:
+      type: 'func()'
+      description: >
+        A function to run at cleanup time.
+  return:
+    type: 'Void'
+    description: >
+      Nothing.
+  example: |
+    at_cleanup(func()
+        (/tmp/file.txt).remove(ignore_missing=yes)
+    )
+
 getenv:
   short: get an environment variable
   description: >
-- 
cgit v1.2.3