From 2c594f726dec883bd6440fe20ce5462c90c55781 Mon Sep 17 00:00:00 2001 From: Kayne Ruse Date: Sun, 19 Feb 2023 03:43:46 +1100 Subject: [PATCH] Wrote docs for arrays and dicts, I think I'm done --- c-api/repl_tools_h.md | 44 +++++++++++++++++++++++++++++++ c-api/toy_literal_array_h.md | 38 ++++++++++++++++++++++++++ c-api/toy_literal_dictionary_h.md | 38 ++++++++++++++++++++++++++ index.md | 6 ++--- 4 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 c-api/repl_tools_h.md create mode 100644 c-api/toy_literal_array_h.md create mode 100644 c-api/toy_literal_dictionary_h.md diff --git a/c-api/repl_tools_h.md b/c-api/repl_tools_h.md new file mode 100644 index 0000000..00b3362 --- /dev/null +++ b/c-api/repl_tools_h.md @@ -0,0 +1,44 @@ +# repl_tools.h + +This header provides a number of tools for compiling and running Toy, and is used primarily by the repl. However, it can also be modified and used by any host program with little effort. + +This is not a core part of the Toy library, and as such `repl_tools.h` and `repl_tools.c` can both be found in the `repl/` folder. + +### const char* Toy_readFile(const char* path, size_t* fileSize) + +This function reads in a file, and returns it as a constant buffer. It also sets the variable pointed to by `fileSize` to the size of the given buffer. + +On error, this function returns `NULL`. + +### int Toy_writeFile(const char* path, const unsigned char* bytes, size_t size) + +This function writes the buffer pointed to by `bytes` to a file specified by `path`. The buffer's size should be specified by `size`. + +On error, this function returns a non-zero value. + +### const unsigned char* Toy_compileString(const char* source, size_t* size) + +This function takes a cstring of Toy source code, and returns a compiled buffer based on that source code. The variable pointed to by `size` is set to the size of the bytecode. + +On error, this function returns `NULL`. + +### void Toy_runBinary(const unsigned char* tb, size_t size) + +This function takes a bytecode array of `size` size, and executes it. The libraries available to the code are: + +* lib_about +* lib_standard +* lib_runner + +### void Toy_runBinaryFile(const char* fname) + +This function loads in the binary file specified by `fname`, and passes it to `Toy_runBinary`. + +### void Toy_runSource(const char* source) + +This function compiles the source with `Toy_compileString`, and passes it to `Toy_runBinary`. + +### void Toy_runSourceFile(const char* fname) + +This function loads in the file specified by `fname`, compiles it, and passes it to `Toy_runBinary`. + diff --git a/c-api/toy_literal_array_h.md b/c-api/toy_literal_array_h.md new file mode 100644 index 0000000..6f9cf6b --- /dev/null +++ b/c-api/toy_literal_array_h.md @@ -0,0 +1,38 @@ +# literal_array.h + +This header defines the structure `Toy_LiteralArray`, which manages a series of `Toy_Literal` instances in sequential memory. The array does not take ownership of given literals, instead it makes an internal copy. + +The array type is one of two fundemental data structures used throughout Toy - the other is the dictionary. + +## Defined Functions + +### void Toy_initLiteralArray(Toy_LiteralArray* array) + +This function initializes a `Toy_LiteralArray` pointed to by `array`. + +### void Toy_freeLiteralArray(Toy_LiteralArray* array) + +This function frees a `Toy_LiteralArray` pointed to by `array`. Every literal within is passed to `Toy_freeLiteral` before its memory is released. + +### int Toy_pushLiteralArray(Toy_LiteralArray* array, Toy_Literal literal) + +This function adds a new `literal` to the end of the `array`, growing the array's internal buffer if needed. + +This function returns the index of the inserted value. + +### Toy_Literal Toy_popLiteralArray(Toy_LiteralArray* array) + +This function removes the literal at the end of the `array`, and returns it. + +### bool Toy_setLiteralArray(Toy_LiteralArray* array, Toy_Literal index, Toy_Literal value) + +This function frees the literal at the position represented by the integer literal `index`, and stores `value` in its place. + +This function returns true on success, otherwise it returns false. + +### Toy_Literal Toy_getLiteralArray(Toy_LiteralArray* array, Toy_Literal index) + +This function returns the literal at the position represented by the integer literal `index`, or returns a null literal if none is found. + +If `index` is not an integer literal or is out of bounds, this function returns a null literal. + diff --git a/c-api/toy_literal_dictionary_h.md b/c-api/toy_literal_dictionary_h.md new file mode 100644 index 0000000..f50f3d6 --- /dev/null +++ b/c-api/toy_literal_dictionary_h.md @@ -0,0 +1,38 @@ +# toy_literal_dictionary.h + +This header defines the structure `Toy_LiteralDictionary`, which manages a series of `Toy_Literal` instances stored in a key-value hash map. The dictionary does not take ownership of given literals, instead it makes an internal copy. + +The dictionary type is one of two fundemental data structures used throughout Toy - the other is the array. + +## Defined Functions + +### void Toy_initLiteralDictionary(Toy_LiteralDictionary* dictionary); + +This function initializes the `Toy_LiteralDictionary` pointed to by `dictionary`. + +### void Toy_freeLiteralDictionary(Toy_LiteralDictionary* dictionary); + +This function frees a `Toy_LiteralDictionary` pointed to by `dictionary`. Every literal within is passed to `Toy_freeLiteral` before its memory is released. + +### void Toy_setLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key, Toy_Literal value); + +This function inserts the given key-value pair of literals into `dictionary`, creating it if it doesn't exist, or freeing and overwriting it if `key` is already present. This function may also expand the memory buffer if needed. + +Literal functions and opaques cannot be used as keys. + +### Toy_Literal Toy_getLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key); + +This function returns the value of the literal within `dictionary` identified by `key`, or a null literal if it doesn't exist. + +Literal functions and opaques cannot be used as keys. + +### void Toy_removeLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key); + +This function removes the key-value pair of literals from `dictionary` identified by `key`, if it exists. + +Literal functions and opaques cannot be used as keys. + +### bool Toy_existsLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key); + +This function returns true if the key-value pair identified by `key` exists within `dictionary`, otherwise it returns false. + diff --git a/index.md b/index.md index bdd8114..7ce6aac 100644 --- a/index.md +++ b/index.md @@ -68,13 +68,13 @@ print tally(); //3
-* [repl_tools.h] +* [repl_tools.h](c-api/repl_tools_h.md) * [toy_common.h](c-api/toy_common_h.md) * [toy_compiler.h](c-api/toy_compiler_h.md) * [toy_interpreter.h](c-api/toy_interpreter_h.md) * [toy_lexer.h](c-api/toy_lexer_h.md) -* [toy_literal_array.h] -* [toy_literal_dictionary.h] +* [toy_literal_array.h](c-api/toy_literal_array_h.md) +* [toy_literal_dictionary.h](c-api/toy_literal_dictionary_h.md) * [toy_literal.h](c-api/toy_literal_h.md) * [toy_memory.h](c-api/toy_memory_h.md) * [toy_parser.h](c-api/toy_parser_h.md)