diff --git a/src/include/ast.h b/src/include/ast.h index 21f3db9..55e7343 100644 --- a/src/include/ast.h +++ b/src/include/ast.h @@ -3,6 +3,7 @@ #include +// The type of an `AST`. typedef enum { // Primitive types. AST_TYPE_NUM, // A number (float). @@ -24,26 +25,38 @@ typedef enum { AST_TYPE_MAX = AST_TYPE_BLOCK, } ASTType; +// An Abstract Syntax Tree. typedef struct { - ASTType type; - void* data; + ASTType type; // The type of the `AST`. + void* data; // The data of the `AST`. } AST; +// Create a new `AST`. AST* ast_init(ASTType type, void* data); +// Destroy an `AST`, recursively. void ast_destroy(AST* ast); +// Print an `AST`, recursively. void ast_print(AST* ast); +// Helper function to `ast_print()`, where `i` is indentation level. void ast_print_i(AST* ast, int i); +// A number. typedef double ASTNumData; +// Create a new `ASTNumData`. ASTNumData* ast_num_data_init(double val); +// Destroy an `ASTNumData`. void ast_num_data_destroy(ASTNumData* num); +// Print an `ASTNumData`. void ast_num_print(ASTNumData*, int i); // An exception. typedef char* ASTExcData; +// Create a new `ASTExecData. ASTExcData ast_exc_data_init(char* msg); +// Destroy an `ASTExecData`. void ast_exc_data_destroy(ASTExcData* exc); +// Print an `ASTExecData`. void ast_exc_print(ASTExcData, int i); // A built-in function. @@ -54,14 +67,18 @@ ASTBIFData* ast_bif_data_init(AST* fn(size_t, AST**)); // There is no `ASTBIFData` destroy function, as function pointers are immortal. +// A call (to a function). typedef struct { char* to; // What the call's to. size_t argc; // Argument count. AST** argv; // Argument vector. } ASTCallData; +// Create a new `ASTCallData`. ASTCallData* ast_call_data_init(char* to, size_t argc, AST** argv); +// Destroy an `ASTCallData`. void ast_call_data_destroy(ASTCallData* call); +// Print an `ASTCallData`. void ast_call_print(ASTCallData*, int i); // A variable definition's data. @@ -70,9 +87,11 @@ typedef struct { AST* val; } ASTVDefData; +// Create a new `ASTVDefData`. ASTVDefData* ast_vdef_data_init(char* name, AST* val); -// Destroys the vdef, its name, and its ->val. +// Destroys the `ASTVDefData`, `ASTVDefData->name`, and `ASTVDefData->val`. void ast_vdef_data_destroy(ASTVDefData* vdef); +// Print an `ASTVDefData`. void ast_vdef_print(ASTVDefData*, int depth); // A variable reference's data. @@ -80,18 +99,24 @@ typedef struct { char* to; // What the reference's to. } ASTVrefData; +// Create a new `ASTVRefData`. ASTVrefData* ast_vref_data_init(char* to); +// Destroy an `ASTVRefData`. void ast_vref_data_destroy(ASTVrefData* call); +// Print an `ASTVRefData`. void ast_vref_print(ASTVrefData*, int i); +// A code block. typedef struct { AST** inside; // What's inside the block. size_t ln; // How many ASTs are in the block. } ASTBlockData; +// Create a new `ASTBlockData`. ASTBlockData* ast_block_data_init(AST** inside, size_t ln); -// Destroy a block. Also destroy all ASTs inside. +// Destroy an `ASTBlockData`, recursively. void ast_block_data_destroy(ASTBlockData* block); +// Print an `ASTBlockData`. void ast_block_print(ASTBlockData*, int i); #endif diff --git a/src/include/dlist.h b/src/include/dlist.h index dd57e36..57c1b06 100644 --- a/src/include/dlist.h +++ b/src/include/dlist.h @@ -11,12 +11,14 @@ typedef struct { size_t ln; // The number of elements in the list. } DList; +// Create a new `DList`. DList* dlist_init(void); +// Destroy a `DList`. void dlist_destroy(DList* dstr); -// Destroy DList structure but preserve ->buf. +// Destroy `DList` structure but preserve `->buf`. void dlist_destroypsv(DList* dstr); -// Append src to dest. +// Append `src` to `dest`. void dlist_append(DList* dest, void* src); #endif diff --git a/src/include/dstr.h b/src/include/dstr.h index 976a1f1..fa7e7a7 100644 --- a/src/include/dstr.h +++ b/src/include/dstr.h @@ -11,15 +11,17 @@ typedef struct { size_t ln; // The number of characters in the buffer. } Dstr; +// Initialize a `DStr`. Dstr* dstr_init(void); +// Destroy a `DStr`. void dstr_destroy(Dstr* dstr); -// Destroy Dstr structure but preserve ->buf. +// Destroy `DStr` structure but preserve `DStr->buf`. void dstr_destroypsv(Dstr* dstr); -// Append ln characters of src to dest. +// Append `ln` characters of `src` to `dest`. void dstr_append(Dstr* dest, char* src, size_t ln); -// Append ch to dest. +// Append `ch` to `dest`. void dstr_appendch(Dstr* dest, char ch); #endif diff --git a/src/include/exec.h b/src/include/exec.h index a6b0c81..b30b9c6 100644 --- a/src/include/exec.h +++ b/src/include/exec.h @@ -9,11 +9,17 @@ extern Stack* scope; // Start executing at the root of the AST. Initialize the `scope`. AST* exec_start(AST* ast); +// Execute an expression. Delegates to the other executor functions. AST* exec_exp(AST* ast); +// Execute the expressions of a block. AST* exec_block(AST* ast); +// Execute a call. AST* exec_call(AST* ast); +// Execute a variable reference. AST* exec_vref(AST* ast); +// Execute a variable definition. AST* exec_vdef(AST* ast); +// Print the result of an execution. void exec_print(double n); #endif diff --git a/src/include/fnv1a.h b/src/include/fnv1a.h index 5992f84..5f64ed7 100644 --- a/src/include/fnv1a.h +++ b/src/include/fnv1a.h @@ -12,6 +12,7 @@ // Offset basis. #define FNV1A_BASIS_64 0xcbf29ce484222325u +// Hash a string `str` of length `ln`. uint64_t fnv1a_hash(char* str, size_t ln); #endif diff --git a/src/include/util.h b/src/include/util.h index 5159da7..0a0549c 100644 --- a/src/include/util.h +++ b/src/include/util.h @@ -1,6 +1,9 @@ #ifndef UTIL_H #define UTIL_H +// Most of this file is cursed printing macros for `ast_print()`. Do not attempt +// to comprehend. + #ifdef DBG // Debug macros // Log a message.