From 9e30b99547d51357b80c97212e2db13e0eed003f Mon Sep 17 00:00:00 2001 From: Kayne Ruse Date: Thu, 16 Feb 2023 22:58:08 +1100 Subject: [PATCH] Wrote the Toy_Compiler docs --- c-api/toy_compiler_h.md | 32 ++++++++++++++++++++++++++++++++ index.md | 4 ++-- 2 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 c-api/toy_compiler_h.md diff --git a/c-api/toy_compiler_h.md b/c-api/toy_compiler_h.md new file mode 100644 index 0000000..e96fecc --- /dev/null +++ b/c-api/toy_compiler_h.md @@ -0,0 +1,32 @@ +# toy_compiler.h + +This header defines the structure `Toy_Compiler`, which is used to transform abstract syntax trees into usable intermediate bytecode. + +There are two steps to generating intermediate 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](c-api/toy_common_h.md)) 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. + +Executing these functions out-of-order causes undefiend behaviour. + +## Defined Functions + +### void Toy_initCompiler(Toy_Compiler* compiler) + +This function initializes the given `Toy_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`. + +### void Toy_freeCompiler(Toy_Compiler* compiler) + +This function frees a `Toy_Compiler`. Calling this on a compiler which has not been collated will free that compiler as expected - anything written to it will be lost. + +### unsigned char* Toy_collateCompiler(Toy_Compiler* compiler, size_t* size) + +This function returns a buffer of bytes, known as "bytecode", created from the given `Toy_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. + diff --git a/index.md b/index.md index 980fa59..a743c24 100644 --- a/index.md +++ b/index.md @@ -63,14 +63,14 @@ print tally(); //3 * [repl_tools.h] * [toy_ast_node.h](c-api/toy_ast_node_h.md) * [toy_common.h](c-api/toy_common_h.md) -* [toy_compiler.h] +* [toy_compiler.h](c-api/toy_compiler_h.md) * [toy_interpreter.h] * [toy_lexer.h](c-api/toy_lexer_h.md) * [toy_literal_array.h] * [toy_literal_dictionary.h] * [toy_literal.h] * [toy_memory.h] -* [toy_parser.h] +* [toy_parser.h](c-api/toy_parser_h.md) * [toy_refstring.h] * [toy_scope.h]