krgamestudios/Toy
1
0
Fork 0
mirror of https://github.com/krgamestudios/Toy.git synced 2026-04-15 14:54:07 +10:00
Code Issues Packages Projects Releases Wiki Activity

Added mecha-style comment docs to a bunch of headers

Browse Source
This commit is contained in:
Kayne Ruse
2023-07-20 19:44:40 +10:00
parent 3d7d1179c9
commit cdfe17ad53
20 changed files with 1175 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
source/toy_compiler.h
View File

@@ -1,11 +1,20 @@
#pragma once
/*!
# toy_compiler.h
This header defines the compiler structure, which is used to transform abstract syntax trees into usable intermediate bytecode. There are two steps to generating bytecode - the writing step, and the collation step.
During the writing step, the core of the program is generated, along with a series of literals representing the values within the program; these values are compressed and flattened into semi-unrecognizable forms. If the same literal is used multiple times in a program, such as a variable name, the name itself is replaced by a reference to the flattened literals within the cache.
During the collation step, everything from the core program’s execution instructions, the flattened literals, the functions (which have their own sections and protocols within the bytecode) and version information (such as the macros defined in toy_common.h) are all combined into a single buffer of bytes, known as bytecode. This bytecode can then be safely saved to a file or immediately executed.
!*/
#include "toy_common.h"
#include "toy_opcodes.h"
#include "toy_ast_node.h"
#include "toy_literal_array.h"
//the compiler takes the nodes, and turns them into sequential chunks of bytecode, saving literals to an external array
typedef struct Toy_Compiler {
Toy_LiteralArray literalCache;
unsigned char* bytecode;
@@ -14,9 +23,38 @@ typedef struct Toy_Compiler {
bool panic;
} Toy_Compiler;
TOY_API void Toy_initCompiler(Toy_Compiler* compiler);
TOY_API void Toy_writeCompiler(Toy_Compiler* compiler, Toy_ASTNode* node);
TOY_API void Toy_freeCompiler(Toy_Compiler* compiler);
/*!
## Define Functions
//embed the header, data section, code section, function section, etc.
Executing the following functions out-of-order causes undefiend behaviour.
!*/
/*!
### void Toy_initCompiler(Toy_Compiler* compiler)
This function initializes the given compiler.
!*/
TOY_API void Toy_initCompiler(Toy_Compiler* compiler);
/*!
### void Toy_writeCompiler(Toy_Compiler* compiler, Toy_ASTNode* node)
This function writes the given `node` argument to the compiler. During the writing step, this function may be called repeatedly, with a stream of results from `Toy_scanParser()`, until `Toy_scanParser()` returns `NULL`.
!*/
TOY_API void Toy_writeCompiler(Toy_Compiler* compiler, Toy_ASTNode* node);
/*!
### unsigned char* Toy_collateCompiler(Toy_Compiler* compiler, size_t* size)
This function returns a buffer of bytes, known as "bytecode", created from the given compiler; it also stores the size of the bytecode in the variable pointed to by `size`.
Calling `Toy_collateCompiler()` multiple times on the same compiler will produce undefined behaviour.
!*/
TOY_API unsigned char* Toy_collateCompiler(Toy_Compiler* compiler, size_t* size);
/*!
### void Toy_freeCompiler(Toy_Compiler* compiler)
This function frees a compiler. Calling this on a compiler which has not been collated will free that compiler as expected - anything written to it will be lost.
!*/
TOY_API void Toy_freeCompiler(Toy_Compiler* compiler);