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/builtins.yaml | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

(limited to 'api/builtins.yaml')

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