From 6d89e9697b1740366f23387964122d264475b49c Mon Sep 17 00:00:00 2001
From: Mistivia <i@mistivia.com>
Date: Tue, 1 Jul 2025 11:29:23 +0800
Subject: add docs

---
 Readme.md          |  7 +++---
 docs/builtins.md   | 22 +++++++++++++++++
 docs/primitives.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++------
 src/builtins.h     | 19 ---------------
 4 files changed, 88 insertions(+), 29 deletions(-)

diff --git a/Readme.md b/Readme.md
index 63b83d9..1a0ca59 100644
--- a/Readme.md
+++ b/Readme.md
@@ -62,6 +62,10 @@ You can use `load` to load a lisp script into the interpreter:
 (load "my-script.lisp")
 ```
 
+## Documents (WIP)
+
+- [Primitives](https://github.com/mistivia/bamboo-lisp/blob/master/docs/primitives.md)
+
 ## Example
 
 See `tests/` for more examples.
@@ -108,7 +112,4 @@ See `tests/` for more examples.
 ;; ... (10 times)
 ```
 
-## Documents (WIP)
-
-- [Primitives](https://github.com/mistivia/bamboo-lisp/blob/master/docs/primitives.md)
 
diff --git a/docs/builtins.md b/docs/builtins.md
index e69de29..0399247 100644
--- a/docs/builtins.md
+++ b/docs/builtins.md
@@ -0,0 +1,22 @@
+# Built-in Functions
+
+## Type Predicate
+
+## Control Flow
+
+## List
+
+## Boolean
+
+## Character
+
+## String
+
+## Symbol
+
+## Number & Math
+
+## Bitwise Operation
+
+## Debug
+
diff --git a/docs/primitives.md b/docs/primitives.md
index b82fdde..fc2d0e4 100644
--- a/docs/primitives.md
+++ b/docs/primitives.md
@@ -9,10 +9,10 @@ that is expected to throw exceptions.
 
 ```lisp
 (assert-exception (throw "This is an exception."))
-    ;; -> #t
+;; -> #t
 
 (assert-exception (+ 1 2))
-    ;; -> Error
+;; -> Error
 ```
 
 ---
@@ -23,10 +23,10 @@ Evaluates *form*. If *form* results in an **error signal**, `assert-error` retur
 
 ```lisp
 (assert-error (error "This is an error."))
-    ;; -> #t
+;; -> #t
 
 (assert-error (+ 1 2))
-    ;; -> Error
+;; -> Error
 ```
 
 ---
@@ -39,16 +39,71 @@ The `try` primitive evaluates the given ***expression***. If the evaluation of *
 (try
   (throw "Alas!")
   (lambda (e) (concat "Caught exception: " e)))
-    ;; -> "Caught exception: Alas!"
+;; -> "Caught exception: Alas!"
 
 (try
   (+ 1 2)
   (lambda (e) (concat "Caught exception: " e)))
-    ;; -> 3
+;; -> 3
 
 (try
   (+ 1 2)
   'not-a-function)
-    ;; -> Error: try: syntax error, catch is not a function.
+;; -> Error: try: syntax error, catch is not a function.
 ```
 
+---
+
+**(load *filename*)**
+
+Evaluates the Lisp expressions contained in the file specified by `filename`. The `filename` argument must be a string. This primitive can only be called from the top-level environment.
+
+```lisp
+(load "my-program.lisp")
+;; -> <Result of the last expression in my-program.lisp>
+```
+
+---
+
+**(return *expression*)**
+
+Evaluates `expression` and returns its value from the current **function**. If `expression` is omitted, `return` evaluates to **nil**. It's important to note that `return` only exits functions and does not break out of `let` blocks or other control structures.
+
+```lisp
+(defun my-func (x)
+    (if (> x 10)
+        (return "Value too large!")
+        (+ x 5)))
+;; -> my-func
+
+(my-func 5)
+;; -> 10
+
+(my-func 12)
+;; -> "Value too large!"
+```
+
+---
+
+**(break)**
+
+This primitive immediately exits the innermost enclosing loop or iteration construct. It's analogous to the `break` statement in C. The `break` primitive takes no arguments.
+
+```lisp
+(defun count-to-five ()
+    (let ((i 0))
+        (while #t
+            (setq i (+ i 1))
+            (when (> i 5)
+                (break))
+            (print i))))
+;; -> count-to-five
+
+(count-to-five)
+;; 1
+;; 2
+;; 3
+;; 4
+;; 5
+;; -> ()
+```
diff --git a/src/builtins.h b/src/builtins.h
index 70f58fd..66d6d1a 100644
--- a/src/builtins.h
+++ b/src/builtins.h
@@ -46,25 +46,6 @@ SExpRef builtin_concat(Interp *interp, SExpRef args);
 SExpRef builtin_print(Interp *interp, SExpRef args);
 SExpRef builtin_princ(Interp *interp, SExpRef args);
 
-SExpRef builtin_abs(Interp *interp, SExpRef args);
-SExpRef builtin_pow(Interp *interp, SExpRef args);
-SExpRef builtin_floor(Interp *interp, SExpRef args);
-SExpRef builtin_truncate(Interp *interp, SExpRef args);
-SExpRef builtin_ceiling(Interp *interp, SExpRef args);
-SExpRef builtin_round(Interp *interp, SExpRef args);
-SExpRef builtin_sin(Interp *interp, SExpRef args);
-SExpRef builtin_cos(Interp *interp, SExpRef args);
-SExpRef builtin_tan(Interp *interp, SExpRef args);
-SExpRef builtin_asin(Interp *interp, SExpRef args);
-SExpRef builtin_acos(Interp *interp, SExpRef args);
-SExpRef builtin_atan(Interp *interp, SExpRef args);
-SExpRef builtin_ln(Interp *interp, SExpRef args);
-SExpRef builtin_log10(Interp *interp, SExpRef args);
-SExpRef builtin_log2(Interp *interp, SExpRef args);
-SExpRef builtin_exp(Interp *interp, SExpRef args);
-SExpRef builtin_min(Interp *interp, SExpRef args);
-SExpRef builtin_max(Interp *interp, SExpRef args);
-
 SExpRef builtin_add(Interp *interp, SExpRef args);
 SExpRef builtin_sub(Interp *interp, SExpRef args);
 SExpRef builtin_mul(Interp *interp, SExpRef args);
-- 
cgit v1.0