Feat/apply

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## [Unreleased changes] - 2026-XX-YY
+### Added
+- `apply` function: `(apply func [args...])`, to call a function with a set of arguments stored in a list. Works with functions, closures and builtins
+- `+`, `-`, `*`, `/` and many other operators can now be passed around, like builtins. This now works: `(list:reduce [1 2 3] +)`, where before we would get a compile time error about a "freestanding operator '+'"
+
 ## [4.2.0] - 2026-02-04
 ### Breaking changes
 - `assert` is no longer an instruction but a builtin

src/arkreactor/Builtins/Builtins.txt → docs/arkdoc/Builtins.txt

@@ -34,6 +34,17 @@
 * =end
 #--
 
+--#
+* @name assert
+* @brief Interrupt the execution if a given condition is false
+* @param cond condition
+* @param message string to display
+* =begin
+* (let a 5)
+* (assert (>= a 4) "'a' must be at least 4")
+* =end
+#--
+
 --#
 * @name nil?
 * @brief Check if a value is nil

src/arkreactor/Builtins/List.txt → docs/arkdoc/List.txt

@@ -22,6 +22,86 @@
 * =end
 #--
 
+--#
+* @name append
+* @brief Add an element to a list, returning a new list
+* @param lst a list
+* @param element
+* =begin
+* (print (append [] 1))  # [1]
+* (print (append [1 2] [3]))  # [1 2 [3]]
+* =end
+#--
+
+--#
+* @name append!
+* @brief Add an element to a list, modifying it in place. It doesn't return anything
+* @param lst a list. Must be mutable
+* @param element
+* =begin
+* (mut lst [1 2])
+* (append! lst 1)
+* (print lst) # [1 2 1]
+* (append! lst [3])
+* (print lst) # [1 2 1 [3]]
+* =end
+#--
+
+--#
+* @name concat
+* @brief Concatenate two lists, returning a new list
+* @param lhs a list
+* @param rhs a second list
+* =begin
+* (print (append [] 1))  # [1]
+* (print (append [1 2] [3]))  # [1 2 [3]]
+* =end
+#--
+
+--#
+* @name concat!
+* @brief Concatenate two lists in place, modifying the first one it in place. It doesn't return anything
+* @param lst a list. Must be mutable
+* @param more another list
+* =begin
+* (mut lst [1 2])
+* (concat! lst [1])
+* (print lst) # [1 2 1]
+* (concat! lst [3])
+* (print lst) # [1 2 1 3]
+* =end
+#--
+
+--#
+* @name pop
+* @brief Return a new list without the element at index
+* @details Supports negative indices, -1 being the end.
+* @param lst a list
+* @param index number
+* =begin
+* (print (pop [1] 0))  # []
+* (print (pop [1 2 3] -2))  # [1 3]
+* (print (pop [1 2 3] 2))  # [1 2]
+* =end
+#--
+
+--#
+* @name pop!
+* @brief Remove an element from a list in place, given its index. It doesn't return anything
+* @details Supports negative indices, -1 being the end.
+* @param lst a list. Must be mutable
+* @param index number
+* =begin
+* (mut lst [1 2 3 4 5])
+* (pop! lst 0)
+* (print lst)  # [2 3 4 5]
+* (pop! lst -2)
+* (print lst)  # [2 3 5]
+* (pop! lst 2)
+* (print lst)  # [2 3]
+* =end
+#--
+
 --#
 * @name head
 * @brief Return the first element of a list, or nil if empty

include/Ark/Builtins/Builtins.hpp

@@ -136,6 +136,32 @@ namespace Ark::internal::Builtins
     {
         ARK_BUILTIN(disassemble);
     }
+
+    namespace Operators
+    {
+        ARK_BUILTIN(add);
+        ARK_BUILTIN(sub);
+        ARK_BUILTIN(mul);
+        ARK_BUILTIN(div);
+        ARK_BUILTIN(mod);
+        ARK_BUILTIN(toNumber);
+        ARK_BUILTIN(toString);
+        ARK_BUILTIN(lessThan);
+        ARK_BUILTIN(lessOrEq);
+        ARK_BUILTIN(greaterThan);
+        ARK_BUILTIN(greaterOrEq);
+        ARK_BUILTIN(eq);
+        ARK_BUILTIN(notEq);
+        ARK_BUILTIN(not_);
+        ARK_BUILTIN(len);
+        ARK_BUILTIN(isEmpty);
+        ARK_BUILTIN(isNil);
+        ARK_BUILTIN(tail);
+        ARK_BUILTIN(head);
+        ARK_BUILTIN(at);
+        ARK_BUILTIN(atAt);
+        ARK_BUILTIN(type);
+    }
 }
 
 #undef ARK_BUILTIN

include/Ark/Compiler/Common.hpp

@@ -134,6 +134,8 @@ namespace Ark::internal
         constexpr std::string_view And = "and";
         constexpr std::string_view Or = "or";
 
+        constexpr std::string_view Apply = "apply";
+
         constexpr std::string_view Undef = "$undef";
         constexpr std::string_view Symcat = "$symcat";
         constexpr std::string_view Argcount = "$argcount";