1 files changed, 644 insertions, 0 deletions
diff --git a/js/scripting-lang/baba-yaga-c/include/baba_yaga.h b/js/scripting-lang/baba-yaga-c/include/baba_yaga.h
new file mode 100644
index 0000000..b8660e1
--- /dev/null
+++ b/js/scripting-lang/baba-yaga-c/include/baba_yaga.h
@@ -0,0 +1,644 @@
+/**
+ * @file baba_yaga.h
+ * @brief Main public API header for Baba Yaga interpreter
+ * @author eli_oat
+ * @version 0.0.1
+ * @date 2025
+ * 
+ * This header provides the public API for the Baba Yaga scripting language
+ * implementation in C. It includes all necessary types, functions, and
+ * constants for interacting with the language interpreter.
+ */
+
+#ifndef BABA_YAGA_H
+#define BABA_YAGA_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Baba Yaga interpreter instance
+ * 
+ * This opaque structure represents a Baba Yaga interpreter instance.
+ * All interpreter operations are performed through this handle.
+ */
+typedef struct Interpreter Interpreter;
+
+/* Forward declarations for internal types */
+typedef struct Scope Scope;
+typedef struct ASTNode ASTNode;
+
+/**
+ * @brief Baba Yaga value types
+ */
+typedef enum {
+    VAL_NUMBER,    /**< Numeric value (double) */
+    VAL_STRING,    /**< String value (char*) */
+    VAL_BOOLEAN,   /**< Boolean value (bool) */
+    VAL_TABLE,     /**< Table value (opaque) */
+    VAL_FUNCTION,  /**< Function value (opaque) */
+    VAL_NIL        /**< Nil/null value */
+} ValueType;
+
+/**
+ * @brief Baba Yaga value structure
+ * 
+ * Represents a value in the Baba Yaga language. The actual data
+ * is stored in the union based on the type field.
+ */
+typedef struct {
+    ValueType type;  /**< Type of the value */
+    union {
+        double number;     /**< Numeric value */
+        char* string;      /**< String value */
+        bool boolean;      /**< Boolean value */
+        void* table;       /**< Table value (opaque) */
+        void* function;    /**< Function value (opaque) */
+    } data;
+} Value;
+
+/**
+ * @brief Baba Yaga execution result
+ */
+typedef enum {
+    EXEC_SUCCESS,      /**< Execution completed successfully */
+    EXEC_ERROR,        /**< Execution failed with error */
+    EXEC_SYNTAX_ERROR, /**< Syntax error in source code */
+    EXEC_RUNTIME_ERROR /**< Runtime error during execution */
+} ExecResult;
+
+/**
+ * @brief Baba Yaga error information
+ */
+typedef struct {
+    char* message;     /**< Error message */
+    int line;          /**< Line number where error occurred */
+    int column;        /**< Column number where error occurred */
+    char* source_file; /**< Source file where error occurred */
+} BabaYagaError;
+
+/* ============================================================================
+ * Core API Functions
+ * ============================================================================ */
+
+/**
+ * @brief Create a new Baba Yaga interpreter instance
+ * 
+ * @return New interpreter instance, or NULL on failure
+ * 
+ * @note The returned interpreter must be freed with baba_yaga_destroy()
+ */
+Interpreter* baba_yaga_create(void);
+
+/**
+ * @brief Destroy a Baba Yaga interpreter instance
+ * 
+ * @param interp Interpreter instance to destroy
+ * 
+ * @note This function frees all memory associated with the interpreter
+ */
+void baba_yaga_destroy(Interpreter* interp);
+
+/**
+ * @brief Execute Baba Yaga source code
+ * 
+ * @param interp Interpreter instance
+ * @param source Source code to execute
+ * @param source_len Length of source code (0 for null-terminated)
+ * @param result Output parameter for execution result
+ * @return Value result of execution
+ * 
+ * @note The returned value must be freed with baba_yaga_value_destroy()
+ */
+Value baba_yaga_execute(Interpreter* interp, const char* source, 
+                       size_t source_len, ExecResult* result);
+
+/**
+ * @brief Execute Baba Yaga source code from file
+ * 
+ * @param interp Interpreter instance
+ * @param filename Path to source file
+ * @param result Output parameter for execution result
+ * @return Value result of execution
+ * 
+ * @note The returned value must be freed with baba_yaga_value_destroy()
+ */
+Value baba_yaga_execute_file(Interpreter* interp, const char* filename,
+                            ExecResult* result);
+
+/* ============================================================================
+ * Value Management Functions
+ * ============================================================================ */
+
+/**
+ * @brief Create a number value
+ * 
+ * @param number Numeric value
+ * @return New number value
+ */
+Value baba_yaga_value_number(double number);
+
+/**
+ * @brief Create a string value
+ * 
+ * @param string String value (will be copied)
+ * @return New string value
+ * 
+ * @note The string is copied internally
+ */
+Value baba_yaga_value_string(const char* string);
+
+/**
+ * @brief Create a boolean value
+ * 
+ * @param boolean Boolean value
+ * @return New boolean value
+ */
+Value baba_yaga_value_boolean(bool boolean);
+
+/**
+ * @brief Create a nil value
+ * 
+ * @return New nil value
+ */
+Value baba_yaga_value_nil(void);
+
+/**
+ * @brief Destroy a Baba Yaga value
+ * 
+ * @param value Value to destroy
+ * 
+ * @note This function frees all memory associated with the value
+ */
+void baba_yaga_value_destroy(Value* value);
+
+/**
+ * @brief Copy a Baba Yaga value
+ * 
+ * @param value Value to copy
+ * @return New copy of the value
+ * 
+ * @note The returned value must be freed with baba_yaga_value_destroy()
+ */
+Value baba_yaga_value_copy(const Value* value);
+
+/* ============================================================================
+ * Table Management Functions
+ * ============================================================================ */
+
+/**
+ * @brief Create a new empty table
+ * 
+ * @return New table value
+ */
+Value baba_yaga_value_table(void);
+
+/**
+ * @brief Get a value from a table by key
+ * 
+ * @param table Table value
+ * @param key Key to look up (string)
+ * @return Value at key, or nil if not found
+ */
+Value baba_yaga_table_get(const Value* table, const char* key);
+
+/**
+ * @brief Set a value in a table by key
+ * 
+ * @param table Table value to modify
+ * @param key Key to set (string)
+ * @param value Value to set
+ * @return New table with the updated value
+ * 
+ * @note Tables are immutable, so this returns a new table
+ */
+Value baba_yaga_table_set(const Value* table, const char* key, const Value* value);
+
+/**
+ * @brief Get a value from a table by numeric index
+ * 
+ * @param table Table value
+ * @param index Numeric index (1-based)
+ * @return Value at index, or nil if not found
+ */
+Value baba_yaga_table_get_index(const Value* table, int index);
+
+/**
+ * @brief Set a value in a table by numeric index
+ * 
+ * @param table Table value to modify
+ * @param index Numeric index (1-based)
+ * @param value Value to set
+ * @return New table with the updated value
+ * 
+ * @note Tables are immutable, so this returns a new table
+ */
+Value baba_yaga_table_set_index(const Value* table, int index, const Value* value);
+
+/**
+ * @brief Get the size of a table
+ * 
+ * @param table Table value
+ * @return Number of elements in the table
+ */
+size_t baba_yaga_table_size(const Value* table);
+
+/**
+ * @brief Check if a table contains a key
+ * 
+ * @param table Table value
+ * @param key Key to check
+ * @return true if key exists, false otherwise
+ */
+bool baba_yaga_table_has_key(const Value* table, const char* key);
+
+/* ============================================================================
+ * Function Management Functions
+ * ============================================================================ */
+
+/**
+ * @brief Create a new function value
+ * 
+ * @param name Function name (can be NULL for anonymous)
+ * @param param_count Number of parameters
+ * @param required_param_count Number of required parameters
+ * @param body Function body (function pointer)
+ * @return New function value
+ */
+Value baba_yaga_value_function(const char* name, Value (*body)(Value*, int), 
+                              int param_count, int required_param_count);
+
+/**
+ * @brief Call a function with arguments
+ * 
+ * @param func Function value to call
+ * @param args Array of argument values
+ * @param arg_count Number of arguments
+ * @param scope Current scope for function execution
+ * @return Result of function call
+ */
+Value baba_yaga_function_call(const Value* func, const Value* args, 
+                             int arg_count, Scope* scope);
+
+/* ============================================================================
+ * Internal Table Management Functions
+ * ============================================================================ */
+
+/**
+ * @brief Increment reference count for a table
+ * 
+ * @param table Table value
+ */
+void table_increment_ref(Value* table);
+
+/**
+ * @brief Decrement reference count for a table
+ * 
+ * @param table Table value
+ */
+void table_decrement_ref(Value* table);
+
+/* ============================================================================
+ * Internal Function Management Functions
+ * ============================================================================ */
+
+/**
+ * @brief Increment reference count for a function
+ * 
+ * @param func Function value
+ */
+void function_increment_ref(Value* func);
+
+/**
+ * @brief Decrement reference count for a function
+ * 
+ * @param func Function value
+ */
+void function_decrement_ref(Value* func);
+
+/* ============================================================================
+ * Function Utility Functions
+ * ============================================================================ */
+
+/**
+ * @brief Get function name
+ * 
+ * @param func Function value
+ * @return Function name, or NULL if anonymous
+ */
+const char* function_get_name(const Value* func);
+
+/**
+ * @brief Get function parameter count
+ * 
+ * @param func Function value
+ * @return Number of parameters
+ */
+int function_get_param_count(const Value* func);
+
+/**
+ * @brief Get function required parameter count
+ * 
+ * @param func Function value
+ * @return Number of required parameters
+ */
+int function_get_required_param_count(const Value* func);
+
+/* ============================================================================
+ * Lexer Functions
+ * ============================================================================ */
+
+/**
+ * @brief Tokenize source code
+ * 
+ * @param source Source code to tokenize
+ * @param source_len Length of source code
+ * @param tokens Output array for tokens
+ * @param max_tokens Maximum number of tokens to read
+ * @return Number of tokens read, or -1 on error
+ */
+int baba_yaga_tokenize(const char* source, size_t source_len, 
+                      void** tokens, size_t max_tokens);
+
+/**
+ * @brief Free tokens
+ * 
+ * @param tokens Array of tokens
+ * @param count Number of tokens
+ */
+void baba_yaga_free_tokens(void** tokens, size_t count);
+
+/* ============================================================================
+ * Parser Functions
+ * ============================================================================ */
+
+/**
+ * @brief Parse source code into AST
+ * 
+ * @param tokens Array of tokens
+ * @param token_count Number of tokens
+ * @return Root AST node, or NULL on error
+ */
+/* ============================================================================
+ * AST Node Types
+ * ============================================================================ */
+
+typedef enum {
+    NODE_LITERAL,
+    NODE_IDENTIFIER,
+    NODE_BINARY_OP,
+    NODE_UNARY_OP,
+    NODE_FUNCTION_CALL,
+    NODE_FUNCTION_DEF,
+    NODE_VARIABLE_DECL,
+    NODE_WHEN_EXPR,
+    NODE_WHEN_PATTERN,
+    NODE_TABLE,
+    NODE_TABLE_ACCESS,
+    NODE_IO_OPERATION,
+    NODE_SEQUENCE
+} NodeType;
+
+void* baba_yaga_parse(void** tokens, size_t token_count);
+
+/**
+ * @brief Destroy AST
+ * 
+ * @param node Root AST node
+ */
+void baba_yaga_destroy_ast(void* node);
+
+/* ============================================================================
+ * AST Accessor Functions
+ * ============================================================================ */
+
+NodeType baba_yaga_ast_get_type(void* node);
+Value baba_yaga_ast_get_literal(void* node);
+const char* baba_yaga_ast_get_identifier(void* node);
+void* baba_yaga_ast_get_function_call_func(void* node);
+int baba_yaga_ast_get_function_call_arg_count(void* node);
+void* baba_yaga_ast_get_function_call_arg(void* node, int index);
+void* baba_yaga_ast_get_binary_op_left(void* node);
+void* baba_yaga_ast_get_binary_op_right(void* node);
+const char* baba_yaga_ast_get_binary_op_operator(void* node);
+void* baba_yaga_ast_get_unary_op_operand(void* node);
+const char* baba_yaga_ast_get_unary_op_operator(void* node);
+const char* baba_yaga_ast_get_function_def_name(void* node);
+int baba_yaga_ast_get_function_def_param_count(void* node);
+void* baba_yaga_ast_get_function_def_param(void* node, int index);
+void* baba_yaga_ast_get_function_def_body(void* node);
+const char* baba_yaga_ast_get_variable_decl_name(void* node);
+void* baba_yaga_ast_get_variable_decl_value(void* node);
+
+/* Sequence node accessors */
+int baba_yaga_ast_get_sequence_statement_count(void* node);
+void* baba_yaga_ast_get_sequence_statement(void* node, int index);
+
+/* When expression accessors */
+void* baba_yaga_ast_get_when_expr_test(void* node);
+int baba_yaga_ast_get_when_expr_pattern_count(void* node);
+void* baba_yaga_ast_get_when_expr_pattern(void* node, int index);
+void* baba_yaga_ast_get_when_pattern_test(void* node);
+void* baba_yaga_ast_get_when_pattern_result(void* node);
+
+/**
+ * @brief Print AST for debugging
+ * 
+ * @param node Root AST node
+ * @param indent Initial indentation level
+ */
+void baba_yaga_print_ast(void* node, int indent);
+
+/* ============================================================================
+ * Debug and Logging Functions
+ * ============================================================================ */
+
+/**
+ * @brief Debug levels
+ */
+typedef enum {
+    DEBUG_NONE = 0,
+    DEBUG_ERROR = 1,
+    DEBUG_WARN = 2,
+    DEBUG_INFO = 3,
+    DEBUG_DEBUG = 4,
+    DEBUG_TRACE = 5
+} DebugLevel;
+
+/**
+ * @brief Set debug level
+ * 
+ * @param level Debug level to set
+ */
+void baba_yaga_set_debug_level(DebugLevel level);
+
+/**
+ * @brief Get current debug level
+ * 
+ * @return Current debug level
+ */
+DebugLevel baba_yaga_get_debug_level(void);
+
+/**
+ * @brief Debug logging function
+ * 
+ * @param level Debug level for this message
+ * @param file Source file name
+ * @param line Line number
+ * @param func Function name
+ * @param format Format string
+ * @param ... Variable arguments
+ */
+void baba_yaga_debug_log(DebugLevel level, const char* file, int line, 
+                        const char* func, const char* format, ...);
+
+/* Debug macros */
+#define DEBUG_ERROR(fmt, ...) \
+    baba_yaga_debug_log(DEBUG_ERROR, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)
+
+#define DEBUG_WARN(fmt, ...) \
+    baba_yaga_debug_log(DEBUG_WARN, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)
+
+#define DEBUG_INFO(fmt, ...) \
+    baba_yaga_debug_log(DEBUG_INFO, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)
+
+#define DEBUG_DEBUG(fmt, ...) \
+    baba_yaga_debug_log(DEBUG_DEBUG, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)
+
+#define DEBUG_TRACE(fmt, ...) \
+    baba_yaga_debug_log(DEBUG_TRACE, __FILE__, __LINE__, __func__, fmt, ##__VA_ARGS__)
+
+/* ============================================================================
+ * Error Handling Functions
+ * ============================================================================ */
+
+/**
+ * @brief Get the last error from an interpreter
+ * 
+ * @param interp Interpreter instance
+ * @return Error information, or NULL if no error
+ * 
+ * @note The returned error must be freed with baba_yaga_error_destroy()
+ */
+BabaYagaError* baba_yaga_get_error(const Interpreter* interp);
+
+/**
+ * @brief Destroy error information
+ * 
+ * @param error Error to destroy
+ * 
+ * @note This function frees all memory associated with the error
+ */
+void baba_yaga_error_destroy(BabaYagaError* error);
+
+/* ============================================================================
+ * Standard Library Functions
+ * ============================================================================ */
+
+/* Core combinator */
+Value stdlib_apply(Value* args, int argc);
+
+/* Arithmetic functions */
+Value stdlib_add(Value* args, int argc);
+Value stdlib_subtract(Value* args, int argc);
+Value stdlib_multiply(Value* args, int argc);
+Value stdlib_divide(Value* args, int argc);
+Value stdlib_modulo(Value* args, int argc);
+Value stdlib_pow(Value* args, int argc);
+Value stdlib_negate(Value* args, int argc);
+
+/* Comparison functions */
+Value stdlib_equals(Value* args, int argc);
+Value stdlib_not_equals(Value* args, int argc);
+Value stdlib_less(Value* args, int argc);
+Value stdlib_less_equal(Value* args, int argc);
+Value stdlib_greater(Value* args, int argc);
+Value stdlib_greater_equal(Value* args, int argc);
+
+/* Logical functions */
+Value stdlib_and(Value* args, int argc);
+Value stdlib_or(Value* args, int argc);
+Value stdlib_xor(Value* args, int argc);
+Value stdlib_not(Value* args, int argc);
+
+/* Function composition */
+Value stdlib_compose(Value* args, int argc);
+
+/* IO functions */
+Value stdlib_out(Value* args, int argc);
+Value stdlib_in(Value* args, int argc);
+Value stdlib_assert(Value* args, int argc);
+
+/* Higher-order functions */
+Value stdlib_map(Value* args, int argc);
+Value stdlib_filter(Value* args, int argc);
+Value stdlib_reduce(Value* args, int argc);
+
+/* ============================================================================
+ * Scope Management Functions
+ * ============================================================================ */
+
+/* Scope creation and destruction */
+Scope* scope_create(Scope* parent);
+void scope_destroy(Scope* scope);
+
+/* Variable operations */
+Value scope_get(Scope* scope, const char* name);
+bool scope_set(Scope* scope, const char* name, Value value);
+bool scope_define(Scope* scope, const char* name, Value value, bool is_constant);
+bool scope_has(Scope* scope, const char* name);
+
+/* Scope utilities */
+int scope_get_names(Scope* scope, char** names, int max_names);
+void scope_print(Scope* scope, int indent);
+
+/* ============================================================================
+ * Utility Functions
+ * ============================================================================ */
+
+/**
+ * @brief Get the type of a value
+ * 
+ * @param value Value to check
+ * @return Type of the value
+ */
+ValueType baba_yaga_value_get_type(const Value* value);
+
+/**
+ * @brief Check if a value is truthy
+ * 
+ * @param value Value to check
+ * @return true if value is truthy, false otherwise
+ */
+bool baba_yaga_value_is_truthy(const Value* value);
+
+/**
+ * @brief Convert a value to string representation
+ * 
+ * @param value Value to convert
+ * @return String representation (must be freed by caller)
+ * 
+ * @note The returned string must be freed with free()
+ */
+char* baba_yaga_value_to_string(const Value* value);
+
+/* ============================================================================
+ * Version Information
+ * ============================================================================ */
+
+/**
+ * @brief Get the Baba Yaga C implementation version
+ * 
+ * @return Version string (do not free)
+ */
+const char* baba_yaga_get_version(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABA_YAGA_H */