mirror of
https://github.com/krgamestudios/Toy.git
synced 2026-04-15 14:54:07 +10:00
Docs now based on comments
This commit is contained in:
@@ -1,36 +1,36 @@
|
||||
# toy_common.h
|
||||
|
||||
This file is generally included in most header files within Toy, as it is where the `TOY_API` macro is defined. It also has some utilities intended for use only by the repl; as such, they won't be documented here.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
### TOY_API
|
||||
|
||||
This definition of this macro is platform-dependant, and used to enable cross-platform compilation of shared and static libraries.
|
||||
|
||||
### TOY_VERSION_MAJOR
|
||||
|
||||
The current major version of Toy. This value is embedded into the bytecode, and the interpreter will refuse to run bytecode with a major version that does not match it's own version.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_MINOR
|
||||
|
||||
The current minor version of Toy. This value is embedded into the bytecode, and the interpreter will refuse to run bytecode with a minor version that is greater than its own minor version.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_PATCH
|
||||
|
||||
The current patch version of Toy. This value is embedded into the bytecode.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_BUILD
|
||||
|
||||
The current build version of Toy. This value is embedded into the bytecode.
|
||||
|
||||
This value is a string, which contains build information such as compilation date and time of the interpreter. When in verbose mode, the compiler will display a warning if the build version of the bytecode does not match the build version of the interpreter.
|
||||
|
||||
This macro may also be used to store information about forks of the Toy codebase.
|
||||
|
||||
|
||||
# toy_common.h
|
||||
|
||||
This file is generally included in most header files within Toy, as it is where the TOY_API macro is defined. It also has some utilities intended for use only by the repl.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
### TOY_API
|
||||
|
||||
This definition of this macro is platform-dependant, and used to enable cross-platform compilation of shared and static libraries.
|
||||
|
||||
### TOY_VERSION_MAJOR
|
||||
|
||||
The current major version of Toy. This value is embedded into the bytecode, and the interpreter will refuse to run bytecode with a major version that does not match it’s own version.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_MINOR
|
||||
|
||||
The current minor version of Toy. This value is embedded into the bytecode, and the interpreter will refuse to run bytecode with a minor version that is greater than its own minor version.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_PATCH
|
||||
|
||||
The current patch version of Toy. This value is embedded into the bytecode.
|
||||
|
||||
This value MUST fit into an unsigned char.
|
||||
|
||||
### TOY_VERSION_BUILD
|
||||
|
||||
The current build version of Toy. This value is embedded into the bytecode.
|
||||
|
||||
This evaluates to a c-string, which contains build information such as compilation date and time of the interpreter. When in verbose mode, the compiler will display a warning if the build version of the bytecode does not match the build version of the interpreter.
|
||||
|
||||
This macro may also be used to store additonal information about forks of the Toy codebase.
|
||||
|
||||
@@ -1,32 +1,30 @@
|
||||
# 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](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.
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
## Define Functions
|
||||
|
||||
Executing the following functions out-of-order causes undefiend behaviour.
|
||||
|
||||
### void Toy_initCompiler(Toy_Compiler* compiler)
|
||||
|
||||
This function initializes the given 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`.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -1,50 +1,54 @@
|
||||
# toy_drive_system.h
|
||||
|
||||
When accessing the file system through toy (such as with lib runner), it's best practice to utilize Toy's built-in drive system - this system (tries to) prevent malicious accessing of files outside of the designated folders. It does this by causing an error when a script tries to access a parent directory.
|
||||
|
||||
To use the drive system, first you must designate specific folders which can be accessed, like so:
|
||||
|
||||
```c
|
||||
#include "toy_drive_system.h"
|
||||
|
||||
int main(int argc, char* argv[]) {
|
||||
//the drive system uses a LiteralDictionary, which must be initialized with this
|
||||
Toy_initDriveSystem();
|
||||
|
||||
Toy_setDrivePath("scripts", "assets/scripts");
|
||||
Toy_setDrivePath("sprites", "assets/sprites");
|
||||
Toy_setDrivePath("fonts", "assets/fonts");
|
||||
|
||||
//TODO: do you stuff here
|
||||
|
||||
//clean up the drive dictionary when you're done
|
||||
Toy_freeDriveSystem();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
This utility is intended mainly for libraries to use - as such, the core of Toy does not utilize it.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initDriveSystem()
|
||||
|
||||
This function initializes the drive system.
|
||||
|
||||
### void Toy_freeDriveSystem()
|
||||
|
||||
This function cleans up after the drive system is no longer needed.
|
||||
|
||||
### void Toy_setDrivePath(char* drive, char* path)
|
||||
|
||||
This function sets a key-value pair in the drive system. It uses C strings, since its intended to be called directly from `main()`.
|
||||
|
||||
### Toy_Literal Toy_getDrivePathLiteral(Toy_Interpreter* interpreter, Toy_Literal* drivePathLiteral)
|
||||
|
||||
This function, when given a string literal of the correct format, will return a new string literal containing the relative filepath to a specified file.
|
||||
|
||||
The correct format is `drive:/path/to/filename`, where `drive` is a drive given to `Toy_setDrivePath()`.
|
||||
|
||||
On failure, this function returns a null literal.
|
||||
|
||||
|
||||
# toy_drive_system.h
|
||||
|
||||
When accessing the file system through toy (such as with the runner library), it's best practice to utilize Toy's built-in drive system - this system (tries to) prevent malicious accessing of files outside of the designated folders. It does this by causing an error when a script tries to access a parent directory.
|
||||
|
||||
To use the drive system, first you must designate specific folders which can be accessed, like so:
|
||||
|
||||
```c
|
||||
#include "toy_drive_system.h"
|
||||
|
||||
int main(int argc, char* argv[]) {
|
||||
//the drive system uses a LiteralDictionary, which must be initialized with this
|
||||
Toy_initDriveSystem();
|
||||
|
||||
Toy_setDrivePath("scripts", "assets/scripts");
|
||||
Toy_setDrivePath("sprites", "assets/sprites");
|
||||
Toy_setDrivePath("fonts", "assets/fonts");
|
||||
|
||||
//TODO: do you stuff here
|
||||
|
||||
//clean up the drive dictionary when you're done
|
||||
Toy_freeDriveSystem();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
This utility is intended mainly for libraries to use - as such, the core of Toy does not utilize it.
|
||||
|
||||
### Implementation Details
|
||||
|
||||
The drive system uses a Toy's Dictionary structure to store the mappings between keys and values - this dictionary object is a static global which persists for the lifetime of the program.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initDriveSystem()
|
||||
|
||||
This function initializes the drive system.
|
||||
|
||||
### void Toy_freeDriveSystem()
|
||||
|
||||
This function cleans up after the drive system is no longer needed.
|
||||
|
||||
### void Toy_setDrivePath(char* drive, char* path)
|
||||
|
||||
This function sets a key-value pair in the drive system. It uses C strings, since its intended to be called directly from `main()`.
|
||||
|
||||
### Toy_Literal Toy_getDrivePathLiteral(Toy_Interpreter* interpreter, Toy_Literal* drivePathLiteral)
|
||||
|
||||
This function, when given a string literal of the correct format, will return a new string literal containing the relative filepath to a specified file.
|
||||
|
||||
The correct format is `drive:/path/to/filename`, where `drive` is a drive that was specified with `Toy_setDrivePath()`.
|
||||
|
||||
On failure, this function returns a null literal.
|
||||
|
||||
@@ -1,124 +1,128 @@
|
||||
# toy_interpreter.h
|
||||
|
||||
This header defines the structure `Toy_Interpreter`, which is the beating heart of Toy.
|
||||
|
||||
The `Toy_Interpreter` is a stack-based, bytecode-driven interpreter with a number of customisation options, including "hooks"; native C functions wrapped in `Toy_Literal` instances, injected in order to give the Toy scripts access to libraries via the `import` keyword. The hooks, when invoked this way, can then inject further native functions into the interpreter's current scope. Exactly which hooks are made available varies by host program, but `standard` is the most commonly included one.
|
||||
|
||||
Another useful customisation feature is the ability to redicrect output from the `print` and `assert` keywords, as well as any internal errors that occur. This can allow you to add in a logging system, or even hook the `print` statement up to some kind of HUD.
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
Note: These interfaces are *actually* defined in [toy_literal.h](toy_literal_h.md) but are documented here, because this is where it matters most.
|
||||
|
||||
### typedef void (*Toy_PrintFn)(const char*)
|
||||
|
||||
This is the interface used by "print functions" - that is, functions used to print messages from the `print` and `assert` keywords, as well as internal interpreter errors.
|
||||
|
||||
### typedef int (*Toy_NativeFn)(struct Toy_Interpreter* interpreter, struct Toy_LiteralArray* arguments)
|
||||
|
||||
This is the interface used by "native functions" - that is, functions written in C which can be called directly by Toy scripts.
|
||||
|
||||
The arguments to the function are passed in as a `Toy_LiteralArray`.
|
||||
|
||||
### typedef int (*Toy_HookFn)(struct Toy_Interpreter* interpreter, struct Toy_Literal identifier, struct Toy_Literal alias)
|
||||
|
||||
This is the interface used by "hook functions" - that is, functions written in C whihc are invoked by using the `import` keyword, and are intended to inject other native functions into the current scope. While hook functions are capable of doing other things, this is greatly discouraged.
|
||||
|
||||
The identifier of the library (its name) is passed in as a `Toy_Literal`, as is any given alias; if no alias is given, then `alias` will be a null literal. Here, the identifier is `standard`, while the alias is `std`.
|
||||
|
||||
```
|
||||
import standard as std;
|
||||
```
|
||||
|
||||
Conventionally, when an alias is given, all of the functions should instead be inserted into a `Toy_LiteralDictionary` which is then inserted into the scope with the alias as its identifier.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function initializes the `Toy_Interpreter`. It allocates memory for internal systems such as the stack, and zeroes-out systems that have yet to be invoked. Internally, it also invokes `Toy_resetInterpreter` to initialize the environment.
|
||||
|
||||
### void Toy_runInterpreter(Toy_Interpreter* interpreter, const unsigned char* bytecode, size_t length)
|
||||
|
||||
This function takes a `Toy_Interpreter` and `bytecode` (as well as the `length` of the bytecode), checks its version information, parses and un-flattens the literal cache, and executes the compiled program stored in the bytecode. This function also consumes the bytecode, so the `bytecode` argument is no longer valid after calls.
|
||||
|
||||
If the given bytecode's embedded version is not compatible with the current interpreter, then this function will refuse to execute.
|
||||
|
||||
Re-using a `Toy_Interpreter` instance without first resetting it is possible (that's how the repl works), however doing so may have unintended consequences if the scripts are not intended to be used in such a way. Any variables declared will persist.
|
||||
|
||||
### void Toy_resetInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function frees any environment that the scripts have built up, and generates a new one. It also injects several globally available functions:
|
||||
|
||||
* set
|
||||
* get
|
||||
* push
|
||||
* pop
|
||||
* length
|
||||
* clear
|
||||
|
||||
### void Toy_freeInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function frees a `Toy_Interpreter`, clearing all of the memory used within. That interpreter is no longer valid for use, and must be re-initialized.
|
||||
|
||||
### bool Toy_injectNativeFn(Toy_Interpreter* interpreter, const char* name, Toy_NativeFn func)
|
||||
|
||||
This function will inject the given native function `func` into the `Toy_Interpreter`'s current scope, with the name passed as `name`. Both the name and function will be converted into literals internally before being stored. It will return true on success, otherwise it will return false.
|
||||
|
||||
The primary use of this function is within hooks.
|
||||
|
||||
### bool Toy_injectNativeHook(Toy_Interpreter* interpreter, const char* name, Toy_HookFn hook)
|
||||
|
||||
This function will inject the given native function `hook` into the `Toy_Interpreter`'s hook cache, with the name passed in as `name`. Both the name and the function will be converted into literals internally before being stored. It will return true on success, otherwise it will return false.
|
||||
|
||||
### bool Toy_callLiteralFn(Toy_Interpreter* interpreter, Toy_Literal func, Toy_LiteralArray* arguments, Toy_LiteralArray* returns)
|
||||
|
||||
This function calls a `Toy_Literal` which contains a function, with the arguments to that function passed in as `arguments` and the results stored in `returns`. It returns true on success, otherwise it returns false.
|
||||
|
||||
The literal `func` can be either a native function or a Toy function, but it won't execute a hook.
|
||||
|
||||
### bool Toy_callFn(Toy_Interpreter* interpreter, const char* name, Toy_LiteralArray* arguments, Toy_LiteralArray* returns)
|
||||
|
||||
This utility function will find a `Toy_literal` within the `Toy_Interpreter`'s scope with a name that matches `name`, and will invoke it using `Toy_callLiteralFn` (passing in `arguments` and `returns` as expected).
|
||||
|
||||
### bool Toy_parseIdentifierToValue(Toy_Interpreter* interpreter, Toy_Literal* literalPtr)
|
||||
|
||||
Sometimes, native functions will receive `Toy_Literal` identifiers instead of the values - the values can be retreived from the given interpreter's scope using the following pattern:
|
||||
|
||||
```c
|
||||
Toy_Literal foobarIdn = foobar;
|
||||
if (TOY_IS_IDENTIFIER(foobar) && Toy_parseIdentifierToValue(interpreter, &foobar)) {
|
||||
freeLiteral(foobarIdn); //remember to free the identifier
|
||||
}
|
||||
```
|
||||
|
||||
### void Toy_setInterpreterPrint(Toy_Interpreter* interpreter, Toy_PrintFn printOutput)
|
||||
|
||||
This function sets the function called by the `print` keyword. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void printWrapper(const char* output) {
|
||||
printf("%s\n", output);
|
||||
}
|
||||
```
|
||||
|
||||
### void Toy_setInterpreterAssert(Toy_Interpreter* interpreter, Toy_PrintFn assertOutput)
|
||||
|
||||
This function sets the function called by the `assert` keyword on failure. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void assertWrapper(const char* output) {
|
||||
fprintf(stderr, "Assertion failure: %s\n", output);
|
||||
}
|
||||
```
|
||||
|
||||
### void Toy_setInterpreterError(Toy_Interpreter* interpreter, Toy_PrintFn errorOutput)
|
||||
|
||||
This function sets the function called when an error occurs within the interpreter. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void errorWrapper(const char* output) {
|
||||
fprintf(stderr, "%s", output); //no newline
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
# toy_interpreter.h
|
||||
|
||||
This header defines the interpreter structure, which is the beating heart of Toy.
|
||||
|
||||
`Toy_Interpreter` is a stack-based, bytecode-driven interpreter with a number of customisation options, including "hooks"; native C functions wrapped in `Toy_Literal` instances, injected into the interpreter in order to give the Toy scripts access to libraries via the `import` keyword. The hooks, when invoked this way, can then inject further native functions into the interpreter's current scope. Exactly which hooks are made available varies by host program, but `standard` is the most commonly included one.
|
||||
|
||||
Another useful customisation feature is the ability to redicrect output from the `print` and `assert` keywords, as well as any internal errors that occur. This can allow you to add in a logging system, or even hook the `print` statement up to some kind of HUD.
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
Note: These interfaces are *actually* defined in [toy_literal.h](toy_literal_h.md) but are documented here, because this is where it matters most.
|
||||
|
||||
### typedef void (*Toy_PrintFn)(const char*)
|
||||
|
||||
This is the interface used by "print functions" - that is, functions used to print messages from the `print` and `assert` keywords, as well as internal interpreter errors.
|
||||
|
||||
### typedef int (*Toy_NativeFn)(struct Toy_Interpreter* interpreter, struct Toy_LiteralArray* arguments)
|
||||
|
||||
This is the interface used by "native functions" - that is, functions written in C which can be called directly by Toy scripts.
|
||||
|
||||
The arguments to the function are passed in as a `Toy_LiteralArray`.
|
||||
|
||||
### typedef int (*Toy_HookFn)(struct Toy_Interpreter* interpreter, struct Toy_Literal identifier, struct Toy_Literal alias)
|
||||
|
||||
This is the interface used by "hook functions" - that is, functions written in C which are invoked by using the `import` keyword, and are intended to inject other native functions into the current scope. While hook functions are capable of doing other things, this is greatly discouraged.
|
||||
|
||||
The identifier of the library (its name) is passed in as a `Toy_Literal`, as is any given alias; if no alias is given, then `alias` will be a null literal. Here, the identifier is `standard`, while the alias is `std`.
|
||||
|
||||
```
|
||||
import standard as std;
|
||||
```
|
||||
|
||||
Conventionally, when an alias is given, all of the functions should instead be inserted into a `Toy_LiteralDictionary` which is then inserted into the scope with the alias as its identifier.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function initializes the interpreter. It allocates memory for internal systems such as the stack, and zeroes-out systems that have yet to be invoked. Internally, it also invokes `Toy_resetInterpreter` to initialize the environment.
|
||||
|
||||
### void Toy_runInterpreter(Toy_Interpreter* interpreter, const unsigned char* bytecode, size_t length)
|
||||
|
||||
This function takes a `Toy_Interpreter` and `bytecode` (as well as the `length` of the bytecode), checks its version information, parses and un-flattens the literal cache, and executes the compiled program stored in the bytecode. This function also consumes the bytecode, so the `bytecode` argument is no longer valid after calls.
|
||||
|
||||
If the given bytecode's embedded version is not compatible with the current interpreter, then this function will refuse to execute.
|
||||
|
||||
Re-using a `Toy_Interpreter` instance without first resetting it is possible (that's how the repl works), however doing so may have unintended consequences if the scripts are not intended to be used in such a way. Any variables declared will persist.
|
||||
|
||||
### void Toy_resetInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function frees any scopes that the scripts have built up, and generates a new one. It also injects several globally available functions:
|
||||
|
||||
* set
|
||||
* get
|
||||
* push
|
||||
* pop
|
||||
* length
|
||||
* clear
|
||||
|
||||
### void Toy_freeInterpreter(Toy_Interpreter* interpreter)
|
||||
|
||||
This function frees a `Toy_Interpreter`, clearing all of the memory used within. That interpreter is no longer valid for use, and must be re-initialized.
|
||||
|
||||
### bool Toy_injectNativeFn(Toy_Interpreter* interpreter, const char* name, Toy_NativeFn func)
|
||||
|
||||
This function will inject the given native function `func` into the `Toy_Interpreter`'s current scope, with the identifer as `name`. Both the name and function will be converted into literals internally before being stored. It will return true on success, otherwise it will return false.
|
||||
|
||||
The primary use of this function is within hooks.
|
||||
|
||||
### bool Toy_injectNativeHook(Toy_Interpreter* interpreter, const char* name, Toy_HookFn hook)
|
||||
|
||||
This function will inject the given native function `hook` into the `Toy_Interpreter`'s hook cache, with the identifier as `name`. Both the name and the function will be converted into literals internally before being stored. It will return true on success, otherwise it will return false.
|
||||
|
||||
Hooks are invoked with the `import` keyword within Toy's scripts.
|
||||
|
||||
### bool Toy_callLiteralFn(Toy_Interpreter* interpreter, Toy_Literal func, Toy_LiteralArray* arguments, Toy_LiteralArray* returns)
|
||||
|
||||
This function calls a `Toy_Literal` which contains a function, with the arguments to that function passed in as `arguments` and the results stored in `returns`. It returns true on success, otherwise it returns false.
|
||||
|
||||
The literal `func` can be either a native function or a Toy function, but it won't execute a hook.
|
||||
|
||||
### bool Toy_callFn(Toy_Interpreter* interpreter, const char* name, Toy_LiteralArray* arguments, Toy_LiteralArray* returns)
|
||||
|
||||
This utility function will find a `Toy_literal` within the `Toy_Interpreter`'s scope with an identifier that matches `name`, and will invoke it using `Toy_callLiteralFn` (passing in `arguments` and `returns` as expected).
|
||||
|
||||
### bool Toy_parseIdentifierToValue(Toy_Interpreter* interpreter, Toy_Literal* literalPtr)
|
||||
|
||||
Sometimes, native functions will receive `Toy_Literal` identifiers instead of the values - the correct values can be retreived from the given interpreter's scope using the following pattern:
|
||||
|
||||
```c
|
||||
Toy_Literal foobarIdn = foobar;
|
||||
if (TOY_IS_IDENTIFIER(foobar) && Toy_parseIdentifierToValue(interpreter, &foobar)) {
|
||||
freeLiteral(foobarIdn); //remember to free the identifier
|
||||
}
|
||||
```
|
||||
|
||||
### void Toy_setInterpreterPrint(Toy_Interpreter* interpreter, Toy_PrintFn printOutput)
|
||||
|
||||
This function sets the function called by the `print` keyword. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void printWrapper(const char* output) {
|
||||
printf("%s\n", output);
|
||||
}
|
||||
```
|
||||
|
||||
Note: The above is a very minor lie - in reality there are some preprocessor directives to allow the repl's `-n` flag to work.
|
||||
|
||||
### void Toy_setInterpreterAssert(Toy_Interpreter* interpreter, Toy_PrintFn assertOutput)
|
||||
|
||||
This function sets the function called by the `assert` keyword on failure. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void assertWrapper(const char* output) {
|
||||
fprintf(stderr, "Assertion failure: %s\n", output);
|
||||
}
|
||||
```
|
||||
|
||||
### void Toy_setInterpreterError(Toy_Interpreter* interpreter, Toy_PrintFn errorOutput)
|
||||
|
||||
This function sets the function called when an error occurs within the interpreter. By default, the following wrapper is used:
|
||||
|
||||
```c
|
||||
static void errorWrapper(const char* output) {
|
||||
fprintf(stderr, "%s", output); //no newline
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1,10 +1,28 @@
|
||||
# toy_lexer.h
|
||||
|
||||
This header defines the structure `Toy_Lexer`, which can be bound to a piece of source code, and used to tokenize it within a parser.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initLexer(Toy_Lexer* lexer, const char* source)
|
||||
|
||||
This function initializes a lexer, binding it to the `source` parameter; the lexer is now ready to be passed to the parser.
|
||||
|
||||
|
||||
# toy_lexer.h
|
||||
|
||||
This header defines the lexer and token structures, which can be bound to a piece of source code, and used to tokenize it within a parser.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initLexer(Toy_Lexer* lexer, const char* source)
|
||||
|
||||
This function initializes a lexer, binding it to the `source` parameter; the lexer is now ready to be passed to the parser.
|
||||
|
||||
### Toy_Token Toy_private_scanLexer(Toy_Lexer* lexer)
|
||||
|
||||
This function "scans" the lexer, returning a token to the parser.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
### void Toy_private_printToken(Toy_Token* token)
|
||||
|
||||
This function prints a given token to stdout.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
### void Toy_private_setComments(Toy_Lexer* lexer, bool enabled)
|
||||
|
||||
This function sets whether comments are allowed within source code. By default, comments are allowed, and are only disabled in the repl.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
@@ -1,38 +1,40 @@
|
||||
# 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.
|
||||
|
||||
|
||||
# literal_array.h
|
||||
|
||||
This header defines the array structure, 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_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.
|
||||
|
||||
### int Toy_private_findLiteralIndex(Toy_LiteralArray* array, Toy_Literal literal)
|
||||
|
||||
This function scans through the array, and returns the index of the first element that matches the given `literal`, otherwise it returns -1.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
@@ -1,38 +1,50 @@
|
||||
# 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.
|
||||
|
||||
|
||||
# toy_literal_dictionary.h
|
||||
|
||||
This header defines the dictionary structure (as well as the private entry structure), 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 Macros
|
||||
|
||||
### TOY_DICTIONARY_MAX_LOAD
|
||||
|
||||
If the contents of a dictionary exceeds this percentage of it's capacity, then a new buffer is created, the old contents are copied over one-by-one, and the original buffer is freed.
|
||||
|
||||
Since this process can be memory and time intensive, a configurable macro is used to allow for fine-grained control across the lang.
|
||||
|
||||
The current default value is `0.75`, representing 75% capacity.
|
||||
|
||||
## 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.
|
||||
|
||||
When expanding the memory buffer, a full copy of the existing dictionary's contents is created - this can be memory intensive.
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,163 +1,183 @@
|
||||
# toy_literal.h
|
||||
|
||||
This header defines the structure `Toy_Literal`, which is used extensively throughout Toy to represent values of some kind.
|
||||
|
||||
The main way of interacting with literals is to use a macro of some kind, as the exact implementation of `Toy_Literal` has and will change based on the needs of Toy.
|
||||
|
||||
User data can be passed around within Toy as an opaque type - use the tag value for determining what kind of opaque it is, or leave it as 0.
|
||||
|
||||
## Defined Enums
|
||||
|
||||
### Toy_LiteralType
|
||||
|
||||
* `TOY_LITERAL_NULL`
|
||||
* `TOY_LITERAL_BOOLEAN`
|
||||
* `TOY_LITERAL_INTEGER`
|
||||
* `TOY_LITERAL_FLOAT`
|
||||
* `TOY_LITERAL_STRING`
|
||||
* `TOY_LITERAL_ARRAY`
|
||||
* `TOY_LITERAL_DICTIONARY`
|
||||
* `TOY_LITERAL_FUNCTION`
|
||||
* `TOY_LITERAL_FUNCTION_NATIVE`
|
||||
* `TOY_LITERAL_FUNCTION_HOOK`
|
||||
* `TOY_LITERAL_IDENTIFIER`
|
||||
* `TOY_LITERAL_TYPE`
|
||||
* `TOY_LITERAL_OPAQUE`
|
||||
* `TOY_LITERAL_ANY`
|
||||
|
||||
These are the main possible values of `Toy_LiteralType`, each of which represents a potential state of the `Toy_Literal` structure. Do not interact with a literal without determining its type with the `IS_*` macros first.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
The following macros are used to determine if a given literal, passed in as `value`, is of a specific type. It should be noted that `TOY_IS_FUNCTION` will return false for native and hook functions.
|
||||
|
||||
* `TOY_IS_NULL(value)`
|
||||
* `TOY_IS_BOOLEAN(value)`
|
||||
* `TOY_IS_INTEGER(value)`
|
||||
* `TOY_IS_FLOAT(value)`
|
||||
* `TOY_IS_STRING(value)`
|
||||
* `TOY_IS_ARRAY(value)`
|
||||
* `TOY_IS_DICTIONARY(value)`
|
||||
* `TOY_IS_FUNCTION(value)`
|
||||
* `TOY_IS_FUNCTION_NATIVE(value)`
|
||||
* `TOY_IS_FUNCTION_HOOK(value)`
|
||||
* `TOY_IS_IDENTIFIER(value)`
|
||||
* `TOY_IS_TYPE(value)`
|
||||
* `TOY_IS_OPAQUE(value)`
|
||||
|
||||
The following macros are used to cast a literal to a specific type to be used.
|
||||
|
||||
* `TOY_AS_BOOLEAN(value)`
|
||||
* `TOY_AS_INTEGER(value)`
|
||||
* `TOY_AS_FLOAT(value)`
|
||||
* `TOY_AS_STRING(value)`
|
||||
* `TOY_AS_ARRAY(value)`
|
||||
* `TOY_AS_DICTIONARY(value)`
|
||||
* `TOY_AS_FUNCTION(value)`
|
||||
* `TOY_AS_FUNCTION_NATIVE(value)`
|
||||
* `TOY_AS_FUNCTION_HOOK(value)`
|
||||
* `TOY_AS_IDENTIFIER(value)`
|
||||
* `TOY_AS_TYPE(value)`
|
||||
* `TOY_AS_OPAQUE(value)`
|
||||
|
||||
The following macros are used to create a new literal, with the given `value` as it's internal value.
|
||||
|
||||
* `TOY_TO_NULL_LITERAL` - does not need parantheses
|
||||
* `TOY_TO_BOOLEAN_LITERAL(value)`
|
||||
* `TOY_TO_INTEGER_LITERAL(value)`
|
||||
* `TOY_TO_FLOAT_LITERAL(value)`
|
||||
* `TOY_TO_STRING_LITERAL(value)`
|
||||
* `TOY_TO_ARRAY_LITERAL(value)`
|
||||
* `TOY_TO_DICTIONARY_LITERAL(value)`
|
||||
* `TOY_TO_FUNCTION_LITERAL(value, l)` - `l` represents the length of the bytecode passed as `value`
|
||||
* `TOY_TO_FUNCTION_NATIVE_LITERAL(value)`
|
||||
* `TOY_TO_FUNCTION_HOOK_LITERAL(value)`
|
||||
* `TOY_TO_IDENTIFIER_LITERAL(value)`
|
||||
* `TOY_TO_TYPE_LITERAL(value, c)` - `c` is the true of the type should be const
|
||||
* `TOY_TO_OPAQUE_LITERAL(value, t)` - `t` is the integer tag
|
||||
|
||||
## More Defined Macros
|
||||
|
||||
The following macros are utilities used throughout Toy's internals, and are available for the user as well.
|
||||
|
||||
### TOY_IS_TRUTHY(x)
|
||||
|
||||
Returns true of the literal `x` is truthy, otherwise it returns false.
|
||||
|
||||
Currently, every value is considered truthy except `false`, which is falsy and `null`, which is neither true or false.
|
||||
|
||||
### TOY_AS_FUNCTION_BYTECODE_LENGTH(lit)
|
||||
|
||||
Returns the length of a Toy function's bytecode.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_FUNCTION`.
|
||||
|
||||
### TOY_MAX_STRING_LENGTH
|
||||
|
||||
The maximum length of a string in Toy, which is 4096 bytes by default. This can be changed at compile time, but the results of doing so are not officially supported.
|
||||
|
||||
### TOY_HASH_I(lit)
|
||||
|
||||
Identifiers are the names of of values within Toy; to speed up execution, their "hash value" is computed at compile time and stored within them. Use this to access it, if needed.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_IDENTIFIER`.
|
||||
|
||||
### TOY_TYPE_PUSH_SUBTYPE(lit, subtype)
|
||||
|
||||
When building a complex type, such as the type of an array or dictionary, you may need to specify inner types. Use this to push a `subtype`. calling `Toy_freeLiteral` on the outermost type should clean up all inner types, as expected.
|
||||
|
||||
This macro returns the index of the newly pushed value within it's parent.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_TYPE`, for both `type` and `subtype`.
|
||||
|
||||
### TOY_GET_OPAQUE_TAG(o)
|
||||
|
||||
Returns the value of the opaque `o`'s tag.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_OPAQUE`.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_freeLiteral(Toy_Literal literal)
|
||||
|
||||
This function frees the given literal's memory. Any internal pointers are now invalid.
|
||||
|
||||
This function should be called on EVERY literal when it is no longer needed, regardless of type.
|
||||
|
||||
### Toy_Literal Toy_copyLiteral(Toy_Literal original)
|
||||
|
||||
This function returns a copy of the given literal. Literals should never be copied without this function, as it handles a lot of internal memory allocations.
|
||||
|
||||
### bool Toy_literalsAreEqual(Toy_Literal lhs, Toy_Literal rhs)
|
||||
|
||||
This checks to see if two given literals are equal.
|
||||
|
||||
When an integer and a float are compared, the integer is cooerced into a float for the duration of the call.
|
||||
|
||||
Arrays and dictionaries are equal only if their keys and values all equal. Likewise, types only equal if all subtypes are equal, in order.
|
||||
|
||||
Functions and opaques are never equal to anything, while values with the type `TOY_LITERAL_ANY` are always equal.
|
||||
|
||||
### int Toy_hashLiteral(Toy_Literal lit)
|
||||
|
||||
This finds the hash of a literal, for various purposes. Different hashing algorithms are used for different types, and some types can't be hashed at all.
|
||||
|
||||
types that can't be hashed are
|
||||
|
||||
* all kinds of functions
|
||||
* type
|
||||
* opaque
|
||||
* any
|
||||
|
||||
In the case of identifiers, their hashes are precomputed on creation and are stored within the literal.
|
||||
|
||||
### void Toy_printLiteral(Toy_Literal literal)
|
||||
|
||||
This wraps a call to `Toy_printLiteralCustom`, with a printf-stdout wrapper as `printFn`.
|
||||
|
||||
### void Toy_printLiteralCustom(Toy_Literal literal, PrintFn printFn)
|
||||
|
||||
This function passes the string representation of `literal` to `printFn`.
|
||||
|
||||
This function is not thread safe - due to the loopy and recursive nature of printing compound values, this function uses some globally persistent variables.
|
||||
|
||||
|
||||
# toy_literal.h
|
||||
|
||||
This header defines the literal structure, which is used extensively throughout Toy to represent values of some kind.
|
||||
|
||||
The main way of interacting with literals is to use a macro of some kind, as the exact implementation of `Toy_Literal` has and will change based on the needs of Toy.
|
||||
|
||||
User data can be passed around within Toy as an opaque type - use the tag value for determining what kind of opaque it is, or leave it as 0.
|
||||
|
||||
## Defined Enums
|
||||
|
||||
### Toy_LiteralType
|
||||
|
||||
* `TOY_LITERAL_NULL`
|
||||
* `TOY_LITERAL_BOOLEAN`
|
||||
* `TOY_LITERAL_INTEGER`
|
||||
* `TOY_LITERAL_FLOAT`
|
||||
* `TOY_LITERAL_STRING`
|
||||
* `TOY_LITERAL_ARRAY`
|
||||
* `TOY_LITERAL_DICTIONARY`
|
||||
* `TOY_LITERAL_FUNCTION`
|
||||
* `TOY_LITERAL_FUNCTION_NATIVE`
|
||||
* `TOY_LITERAL_FUNCTION_HOOK`
|
||||
* `TOY_LITERAL_IDENTIFIER`
|
||||
* `TOY_LITERAL_TYPE`
|
||||
* `TOY_LITERAL_OPAQUE`
|
||||
* `TOY_LITERAL_ANY`
|
||||
|
||||
These are the main values of `Toy_LiteralType`, each of which represents a potential state of the `Toy_Literal` structure. Do not interact with a literal without determining its type with the `IS_*` macros first.
|
||||
|
||||
Other type values are possible, but are only used internally.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
The following macros are used to determine if a given literal, passed in as `value`, is of a specific type. It should be noted that `TOY_IS_FUNCTION` will return false for native and hook functions.
|
||||
|
||||
* `TOY_IS_NULL(value)`
|
||||
* `TOY_IS_BOOLEAN(value)`
|
||||
* `TOY_IS_INTEGER(value)`
|
||||
* `TOY_IS_FLOAT(value)`
|
||||
* `TOY_IS_STRING(value)`
|
||||
* `TOY_IS_ARRAY(value)`
|
||||
* `TOY_IS_DICTIONARY(value)`
|
||||
* `TOY_IS_FUNCTION(value)`
|
||||
* `TOY_IS_FUNCTION_NATIVE(value)`
|
||||
* `TOY_IS_FUNCTION_HOOK(value)`
|
||||
* `TOY_IS_IDENTIFIER(value)`
|
||||
* `TOY_IS_TYPE(value)`
|
||||
* `TOY_IS_OPAQUE(value)`
|
||||
|
||||
The following macros are used to cast a literal to a specific C type to be used.
|
||||
|
||||
* `TOY_AS_BOOLEAN(value)`
|
||||
* `TOY_AS_INTEGER(value)`
|
||||
* `TOY_AS_FLOAT(value)`
|
||||
* `TOY_AS_STRING(value)`
|
||||
* `TOY_AS_ARRAY(value)`
|
||||
* `TOY_AS_DICTIONARY(value)`
|
||||
* `TOY_AS_FUNCTION(value)`
|
||||
* `TOY_AS_FUNCTION_NATIVE(value)`
|
||||
* `TOY_AS_FUNCTION_HOOK(value)`
|
||||
* `TOY_AS_IDENTIFIER(value)`
|
||||
* `TOY_AS_TYPE(value)`
|
||||
* `TOY_AS_OPAQUE(value)`
|
||||
|
||||
The following macros are used to create a new literal, with the given `value` as it's internal value.
|
||||
|
||||
* `TOY_TO_NULL_LITERAL` - does not need parantheses
|
||||
* `TOY_TO_BOOLEAN_LITERAL(value)`
|
||||
* `TOY_TO_INTEGER_LITERAL(value)`
|
||||
* `TOY_TO_FLOAT_LITERAL(value)`
|
||||
* `TOY_TO_STRING_LITERAL(value)`
|
||||
* `TOY_TO_ARRAY_LITERAL(value)`
|
||||
* `TOY_TO_DICTIONARY_LITERAL(value)`
|
||||
* `TOY_TO_FUNCTION_LITERAL(value, l)` - `l` represents the length of the bytecode passed as `value`
|
||||
* `TOY_TO_FUNCTION_NATIVE_LITERAL(value)`
|
||||
* `TOY_TO_FUNCTION_HOOK_LITERAL(value)`
|
||||
* `TOY_TO_IDENTIFIER_LITERAL(value)`
|
||||
* `TOY_TO_TYPE_LITERAL(value, c)` - `c` is the true of the type should be const
|
||||
* `TOY_TO_OPAQUE_LITERAL(value, t)` - `t` is the integer tag
|
||||
|
||||
## More Defined Macros
|
||||
|
||||
The following macros are utilities used throughout Toy's internals, and are available for the user as well.
|
||||
|
||||
### TOY_IS_TRUTHY(x)
|
||||
|
||||
Returns true of the literal `x` is truthy, otherwise it returns false.
|
||||
|
||||
Currently, every value is considered truthy except `false`, which is falsy and `null`, which is neither true or false.
|
||||
|
||||
### TOY_AS_FUNCTION_BYTECODE_LENGTH(lit)
|
||||
|
||||
Returns the length of a Toy function's bytecode.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_FUNCTION`.
|
||||
|
||||
### TOY_MAX_STRING_LENGTH
|
||||
|
||||
The maximum length of a string in Toy, which is 4096 bytes by default. This can be changed at compile time, but the results of doing so are not officially supported.
|
||||
|
||||
### TOY_HASH_I(lit)
|
||||
|
||||
Identifiers are the names of values within Toy; to speed up execution, their "hash value" is computed at compile time and stored within them. Use this to access it, if needed.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_IDENTIFIER`.
|
||||
|
||||
### TOY_TYPE_PUSH_SUBTYPE(lit, subtype)
|
||||
|
||||
When building a complex type, such as the type of an array or dictionary, you may need to specify inner types. Use this to push a `subtype`. calling `Toy_freeLiteral()` on the outermost type should clean up all inner types, as expected.
|
||||
|
||||
This macro returns the index of the newly pushed value within it's parent.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_TYPE`, for both `type` and `subtype`.
|
||||
|
||||
### TOY_GET_OPAQUE_TAG(o)
|
||||
|
||||
Returns the value of the opaque `o`'s tag.
|
||||
|
||||
This macro is only valid on `TOY_LITERAL_OPAQUE`.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_freeLiteral(Toy_Literal literal)
|
||||
|
||||
This function frees the given literal's memory. Any internal pointers are now invalid.
|
||||
|
||||
This function should be called on EVERY literal when it is no longer needed, regardless of type.
|
||||
|
||||
### Toy_Literal Toy_copyLiteral(Toy_Literal original)
|
||||
|
||||
This function returns a copy of the given literal. Literals should never be copied without this function, as it handles a lot of internal memory allocations.
|
||||
|
||||
### bool Toy_literalsAreEqual(Toy_Literal lhs, Toy_Literal rhs)
|
||||
|
||||
This checks to see if two given literals are equal.
|
||||
|
||||
When an integer and a float are compared, the integer is cooerced into a float for the duration of the call.
|
||||
|
||||
Arrays or dictionaries are equal only if their keys and values all equal. Likewise, types only equal if all subtypes are equal, in order.
|
||||
|
||||
Functions and opaques are never equal to anything, while values with the type `TOY_LITERAL_ANY` are always equal.
|
||||
|
||||
### int Toy_hashLiteral(Toy_Literal lit)
|
||||
|
||||
This finds the hash of a literal, for various purposes. Different hashing algorithms are used for different types, and some types can't be hashed at all.
|
||||
|
||||
types that can't be hashed are
|
||||
|
||||
* all kinds of functions
|
||||
* type
|
||||
* opaque
|
||||
* any
|
||||
|
||||
In the case of identifiers, their hashes are precomputed on creation and are stored within the literal.
|
||||
|
||||
### void Toy_printLiteral(Toy_Literal literal)
|
||||
|
||||
This wraps a call to `Toy_printLiteralCustom`, with a printf-stdout wrapper as `printFn`.
|
||||
|
||||
### void Toy_printLiteralCustom(Toy_Literal literal, PrintFn printFn)
|
||||
|
||||
This function passes the string representation of `literal` to `printFn`.
|
||||
|
||||
This function is not thread safe - due to the loopy and recursive nature of printing compound values, this function uses some globally persistent variables.
|
||||
|
||||
### bool Toy_private_isTruthy(Toy_Literal x)
|
||||
|
||||
Utilized by the `TOY_IS_TRUTHY` macro.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
### bool Toy_private_toIdentifierLiteral(Toy_RefString* ptr)
|
||||
|
||||
Utilized by the `TOY_TO_IDENTIFIER_LITERAL` macro.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
### bool Toy_private_typePushSubtype(Toy_Literal* lit, Toy_Literal subtype)
|
||||
|
||||
Utilized by the `TOY_TYPE_PUSH_SUBTYPE` macro.
|
||||
|
||||
Private functions are not intended for general use.
|
||||
|
||||
@@ -1,70 +1,64 @@
|
||||
# toy_memory.h
|
||||
|
||||
This header defines all of the memory management utilities. Any and all heap-based memory management goes through these utilities.
|
||||
|
||||
A default memory allocator function is used internally, but it can be overwritten for diagnostic and platform related purposes.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
### TOY_GROW_CAPACITY(capacity)
|
||||
|
||||
This macro calculates, in place, what size of memory should be allocated based on the previous size.
|
||||
|
||||
### TOY_GROW_CAPACITY_FAST(capacity)
|
||||
|
||||
This macro calculates, in place, what size of memory should be allocated based on the previous size. It grows faster than `TOY_GROW_CAPACITY`.
|
||||
|
||||
### TOY_ALLOCATE(type, count)
|
||||
|
||||
This macro wraps `Toy_reallocate`, which itself calls the allocator function. `type` is the type that will be allocated, and `count` is the number which will be needed (usually calculated with `TOY_GROW_CAPACITY`).
|
||||
|
||||
This returns a pointer of `type`.
|
||||
|
||||
### TOY_FREE(type, pointer)
|
||||
|
||||
This macro wraps `Toy_reallocate`, which itself calls the allocator function. `type` is the type that will be freed, and `pointer` is to what is being freed. This should only be used when a single element has been allocated, as opposed to an array.
|
||||
|
||||
### TOY_FREE_ARRAY(type, pointer, oldCount)
|
||||
|
||||
This macro wraps `Toy_reallocate`, which itself calls the allocator function. `type` is the type that will be freed, `pointer` is a reference to what is being freed, and `oldCount` is the size of the array being freed. This should only be used when an array has been allocated, as opposed to a single element.
|
||||
|
||||
### TOY_GROW_ARRAY(type, pointer, oldCount, count)
|
||||
|
||||
This macro wraps `Toy_reallocate`, which itself calls the allocator function. `type` is the type that is being operated on, `pointer` is what is being resized, `oldCount` is the previous size of the array and `count` is the new size of the array (usually calculated with `TOY_GROW_CAPACITY`).
|
||||
|
||||
This returns a pointer of `type`.
|
||||
|
||||
### TOY_SHRINK_ARRAY(type, pointer, oldCount, count)
|
||||
|
||||
This macro wraps `Toy_reallocate`, which itself calls the allocator function. `type` is the type that is being operated on, `pointer` is what is being resized, `oldCount` is the previous size of the array and `count` is the new size of the array.
|
||||
|
||||
This returns a pointer of `type`.
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_MemoryAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This function interface is used for defining any memory allocator functions.
|
||||
|
||||
Any and all memory allocator functions should:
|
||||
|
||||
* Take a `pointer` to a previously allocated block of memory, or `NULL`
|
||||
* Take the `oldSize`, which is the previous size of the `pointer` allocated, in bytes (`oldSize` can be 0)
|
||||
* Take the `newSize`, which is the new size of the buffer to be allocaated, in bytes (`newSize` can be 0)
|
||||
* Return the newly allocated buffer, or `NULL` if `newSize` is zero
|
||||
* Return `NULL` on error
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### TOY_API void* Toy_reallocate(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This function shouldn't be called directly. Instead, use one of the given macros.
|
||||
|
||||
This function wraps a call to the internal assigned memory allocator.
|
||||
|
||||
### void Toy_setMemoryAllocator(Toy_MemoryAllocatorFn)
|
||||
|
||||
This function sets the memory allocator, replacing the default memory allocator.
|
||||
|
||||
This function also overwrites any given refstring memory allocator, see [toy_refstring.h](toy_refstring_h.md).
|
||||
|
||||
|
||||
# toy_memory.h
|
||||
|
||||
This header defines all of the memory management utilities. Any and all heap-based memory management goes through these utilities.
|
||||
|
||||
A default memory allocator function is used internally, but it can be overwritten for diagnostic and platform related purposes.
|
||||
|
||||
## Defined Macros
|
||||
|
||||
### TOY_GROW_CAPACITY(capacity)
|
||||
|
||||
This macro calculates, in place, what size of memory should be allocated based on the previous size.
|
||||
|
||||
### TOY_GROW_CAPACITY_FAST(capacity)
|
||||
|
||||
This macro calculates, in place, what size of memory should be allocated based on the previous size. It grows faster than `TOY_GROW_CAPACITY`.
|
||||
|
||||
### TOY_FREE(type, pointer)
|
||||
|
||||
This macro wraps `Toy_reallocate()`, which itself calls the allocator function. `type` is the type that will be freed, and `pointer` is to what is being freed. This should only be used when a single element has been allocated, as opposed to an array.
|
||||
|
||||
### TOY_FREE_ARRAY(type, pointer, oldCount)
|
||||
|
||||
This macro wraps `Toy_reallocate()`, which itself calls the allocator function. `type` is the type that will be freed, `pointer` is a reference to what is being freed, and `oldCount` is the size of the array being freed. This should only be used when an array has been allocated, as opposed to a single element.
|
||||
|
||||
### TOY_GROW_ARRAY(type, pointer, oldCount, count)
|
||||
|
||||
This macro wraps `Toy_reallocate()`, which itself calls the allocator function. `type` is the type that is being operated on, `pointer` is what is being resized, `oldCount` is the previous size of the array and `count` is the new size of the array (usually calculated with `TOY_GROW_CAPACITY`).
|
||||
|
||||
This returns a pointer of `type`.
|
||||
|
||||
### TOY_SHRINK_ARRAY(type, pointer, oldCount, count)
|
||||
|
||||
This macro wraps `Toy_reallocate()`, which itself calls the allocator function. `type` is the type that is being operated on, `pointer` is what is being resized, `oldCount` is the previous size of the array and `count` is the new size of the array.
|
||||
|
||||
This returns a pointer of `type`.
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_MemoryAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This function interface is used for defining any memory allocator functions.
|
||||
|
||||
Any and all memory allocator functions should:
|
||||
|
||||
* Take a `pointer` to a previously allocated block of memory, or `NULL`
|
||||
* Take the `oldSize`, which is the previous size of the `pointer` allocated, in bytes (`oldSize` can be 0)
|
||||
* Take the `newSize`, which is the new size of the buffer to be allocaated, in bytes (`newSize` can be 0)
|
||||
* Return the newly allocated buffer, or `NULL` if `newSize` is zero
|
||||
* Return `NULL` on error
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### TOY_API void* Toy_reallocate(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This function shouldn't be called directly. Instead, use one of the given macros.
|
||||
|
||||
This function wraps a call to the internal assigned memory allocator.
|
||||
|
||||
### void Toy_setMemoryAllocator(Toy_MemoryAllocatorFn)
|
||||
|
||||
This function sets the memory allocator, replacing the default memory allocator.
|
||||
|
||||
This function also overwrites any given refstring and reffunction memory allocators, see [toy_refstring.h](toy_refstring_h.md).
|
||||
|
||||
@@ -1,72 +1,72 @@
|
||||
# toy_parser.h
|
||||
|
||||
This header defines the structure `Toy_Parser` which, after being initialized with a `Toy_Lexer` produces a series of abstract syntax trees to be passed to the `Toy_Compiler`. The following is a utility function provided by [repl_tools.h](repl_tools_h.md), demonstrating how to use the parser.
|
||||
|
||||
```c
|
||||
//generate bytecode from a given string
|
||||
const unsigned char* Toy_compileString(const char* source, size_t* size) {
|
||||
//declare the relevant instances
|
||||
Toy_Lexer lexer;
|
||||
Toy_Parser parser;
|
||||
Toy_Compiler compiler;
|
||||
|
||||
//initialize each of them
|
||||
Toy_initLexer(&lexer, source);
|
||||
Toy_initParser(&parser, &lexer);
|
||||
Toy_initCompiler(&compiler);
|
||||
|
||||
//when the parser returns NULL, it is finished
|
||||
Toy_ASTNode* node = Toy_scanParser(&parser);
|
||||
while(node != NULL) {
|
||||
//if the parser returns an error node, clean up and exit gracefully
|
||||
if (node->type == TOY_AST_NODE_ERROR) {
|
||||
Toy_freeASTNode(node);
|
||||
Toy_freeCompiler(&compiler);
|
||||
Toy_freeParser(&parser);
|
||||
//no need to clean the lexer
|
||||
return NULL;
|
||||
}
|
||||
|
||||
//write the node to the compiler
|
||||
Toy_writeCompiler(&compiler, node);
|
||||
Toy_freeASTNode(node);
|
||||
|
||||
//grab the next node
|
||||
node = Toy_scanParser(&parser);
|
||||
}
|
||||
|
||||
//get the bytecode to be returned
|
||||
const unsigned char* tb = Toy_collateCompiler(&compiler, size);
|
||||
|
||||
//cleanup
|
||||
Toy_freeCompiler(&compiler);
|
||||
Toy_freeParser(&parser);
|
||||
//no need to clean the lexer
|
||||
|
||||
//finally
|
||||
return tb;
|
||||
}
|
||||
```
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initParser(Toy_Parser* parser, Toy_Lexer* lexer)
|
||||
|
||||
This function initializes a `Toy_Parser`, binding the given `Toy_Lexer` to it.
|
||||
|
||||
### void Toy_freeParser(Toy_Parser* parser)
|
||||
|
||||
This function frees a `Toy_Parser` once its task is completed.
|
||||
|
||||
### Toy_ASTNode* Toy_scanParser(Toy_Parser* parser)
|
||||
|
||||
This function returns an abstract syntax tree representing part of the program, or an error node. The abstract syntax tree must be passed to `Toy_writeCompiler` and/or `Toy_freeASTNode`.
|
||||
|
||||
This function should be called repeatedly until it returns `NULL`, indicating the end of the program.
|
||||
|
||||
### void Toy_freeASTNode(Toy_ASTNode* node)
|
||||
|
||||
This function cleans up any valid instance of `Toy_ASTNode` pointer passed to it. It is most commonly used to clean up the values returned by `Toy_scanParser`, after they have been passsed to `Toy_writeCompiler`, or when the node is an error node.
|
||||
|
||||
Note: this function is *actually* defined in toy_ast_node.h, but documented here, because this is where it matters most.
|
||||
|
||||
|
||||
# toy_parser.h
|
||||
|
||||
This header defines the parser structure which, after being initialized with a lexer produces a series of abstract syntax trees to be passed to the compiler. The following is a utility function provided by [repl_tools.h](repl_tools_h.md), demonstrating how to use the parser.
|
||||
|
||||
```c
|
||||
//generate bytecode from a given string
|
||||
const unsigned char* Toy_compileString(const char* source, size_t* size) {
|
||||
//declare the relevant instances
|
||||
Toy_Lexer lexer;
|
||||
Toy_Parser parser;
|
||||
Toy_Compiler compiler;
|
||||
|
||||
//initialize each of them
|
||||
Toy_initLexer(&lexer, source);
|
||||
Toy_initParser(&parser, &lexer);
|
||||
Toy_initCompiler(&compiler);
|
||||
|
||||
//when the parser returns NULL, it is finished
|
||||
Toy_ASTNode* node = Toy_scanParser(&parser);
|
||||
while(node != NULL) {
|
||||
//if the parser returns an error node, clean up and exit gracefully
|
||||
if (node->type == TOY_AST_NODE_ERROR) {
|
||||
Toy_freeASTNode(node);
|
||||
Toy_freeCompiler(&compiler);
|
||||
Toy_freeParser(&parser);
|
||||
//no need to clean the lexer
|
||||
return NULL;
|
||||
}
|
||||
|
||||
//write the node to the compiler
|
||||
Toy_writeCompiler(&compiler, node);
|
||||
Toy_freeASTNode(node);
|
||||
|
||||
//grab the next node
|
||||
node = Toy_scanParser(&parser);
|
||||
}
|
||||
|
||||
//get the bytecode to be returned
|
||||
const unsigned char* tb = Toy_collateCompiler(&compiler, size);
|
||||
|
||||
//cleanup
|
||||
Toy_freeCompiler(&compiler);
|
||||
Toy_freeParser(&parser);
|
||||
//no need to clean the lexer
|
||||
|
||||
//finally
|
||||
return tb;
|
||||
}
|
||||
```
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_initParser(Toy_Parser* parser, Toy_Lexer* lexer)
|
||||
|
||||
This function initializes a `Toy_Parser`, binding the given `Toy_Lexer` to it.
|
||||
|
||||
### void Toy_freeParser(Toy_Parser* parser)
|
||||
|
||||
This function frees a `Toy_Parser` once its task is completed.
|
||||
|
||||
### Toy_ASTNode* Toy_scanParser(Toy_Parser* parser)
|
||||
|
||||
This function returns an abstract syntax tree representing part of the program, or an error node. The abstract syntax tree must be passed to `Toy_writeCompiler()` and/or `Toy_freeASTNode()`.
|
||||
|
||||
This function should be called repeatedly until it returns `NULL`, indicating the end of the program.
|
||||
|
||||
### void Toy_freeASTNode(Toy_ASTNode* node)
|
||||
|
||||
This function cleans up any valid instance of `Toy_ASTNode` pointer passed to it. It is most commonly used to clean up the values returned by `Toy_scanParser`, after they have been passsed to `Toy_writeCompiler`, or when the node is an error node.
|
||||
|
||||
Note: this function is *actually* defined in toy_ast_node.h, but documented here, because this is where it matters most.
|
||||
|
||||
@@ -1,46 +1,48 @@
|
||||
# toy_reffunction.h
|
||||
|
||||
This header defines the structure `Toy_RefFunction`, as well as all of the related utilities.
|
||||
|
||||
See [toy_RefString](toy_refstring_h.md) for more information about the reference pattern.
|
||||
|
||||
This module reserves the right to instead preform a deep copy when it sees fit (this is for future debugging purposes).
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_RefFunctionAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This interface conforms to Toy's memory API, and generally shouldn't be used.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_setRefFunctionAllocatorFn(Toy_RefFunctionAllocatorFn)
|
||||
|
||||
This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used.
|
||||
|
||||
### Toy_RefFunction* Toy_createRefFunction(const void* data, size_t length)
|
||||
|
||||
This function returns a new `Toy_RefFunction`, containing a copy of `data`, or `NULL` on error.
|
||||
|
||||
This function also sets the returned `refFunction`'s reference counter to 1.
|
||||
|
||||
### void Toy_deleteRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function reduces the `refFunction`'s reference counter by 1 and, if it reaches 0, frees the memory.
|
||||
|
||||
### int Toy_countRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function returns the total number of references to `refFunction`, for debugging.
|
||||
|
||||
### size_t Toy_lengthRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function returns the length of the underlying bytecode of `refFunction`.
|
||||
|
||||
### Toy_RefFunction* Toy_copyRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function increases the reference counter of `refFunction` by 1, before returning the given pointer.
|
||||
|
||||
### Toy_RefFunction* Toy_deepCopyRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function behaves identically to `Toy_copyRefFunction`, except that it explicitly preforms a deep copy of the internal memory. Using this function should be done carefully, as it incurs a performance penalty that negates the benefit of this module.
|
||||
|
||||
|
||||
# toy_reffunction.h
|
||||
|
||||
This header defines the Toy_RefFunction structure, as well as all of the related utilities.
|
||||
|
||||
See [Toy_RefString](toy_refstring_h.md) for more information about the reference pattern.
|
||||
|
||||
This module reserves the right to instead preform a deep copy when it sees fit (this is for future debugging purposes).
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_RefFunctionAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This interface conforms to Toy's memory API, and generally shouldn't be used without a good reason.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_setRefFunctionAllocatorFn(Toy_RefFunctionAllocatorFn)
|
||||
|
||||
This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used without a good reason.
|
||||
|
||||
### Toy_RefFunction* Toy_createRefFunction(const void* data, size_t length)
|
||||
|
||||
This function returns a new `Toy_RefFunction`, containing a copy of `data`, or `NULL` on error.
|
||||
|
||||
This function also sets the returned `refFunction`'s reference counter to 1.
|
||||
|
||||
### void Toy_deleteRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function reduces the `refFunction`'s reference counter by 1 and, if it reaches 0, frees the memory.
|
||||
|
||||
### int Toy_countRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function returns the total number of references to `refFunction`, for debugging.
|
||||
|
||||
### size_t Toy_lengthRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function returns the length of the underlying bytecode of `refFunction`.
|
||||
|
||||
### Toy_RefFunction* Toy_copyRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function increases the reference counter of `refFunction` by 1, before returning the given pointer.
|
||||
|
||||
This function reserves the right to create a deep copy where needed.
|
||||
|
||||
### Toy_RefFunction* Toy_deepCopyRefFunction(Toy_RefFunction* refFunction)
|
||||
|
||||
This function behaves identically to `Toy_copyRefFunction`, except that it explicitly forces a deep copy of the internal memory. Using this function should be done carefully, as it incurs a performance penalty that negates the benefit of this module.
|
||||
|
||||
@@ -1,67 +1,69 @@
|
||||
# toy_refstring.h
|
||||
|
||||
This header defines the structure `Toy_RefString`, as well as all of the related utilities.
|
||||
|
||||
[refstring](https://github.com/Ratstail91/refstring) is a stand-alone utility written to reduce the amount of memory manipulation used within Toy. It was independantly written and tested, before being incorporated into Toy proper. As such it has it's own memory management API, which by default is tied into Toy's [core memory API](toy_memory_h.md).
|
||||
|
||||
Instances of `Toy_RefString` are reference counted - that is, rather than copying an existing string in memory, a pointer to the refstring is returned, and the internal reference counter is increased by 1. When the pointer is no longer needed, `Toy_DeleteRefString` can be called; this will decrement the internal reference counter by 1, and only free it when it reaches 0. This has multiple benefits, when used correctly:
|
||||
|
||||
* Reduced memory usage
|
||||
* Faster program execution
|
||||
|
||||
This module reserves the right to instead preform a deep copy when it sees fit (this is for future debugging purposes).
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_RefStringAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This interface conforms to Toy's memory API, and generally shouldn't be used.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_setRefStringAllocatorFn(Toy_RefStringAllocatorFn)
|
||||
|
||||
This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used.
|
||||
|
||||
### Toy_RefString* Toy_createRefString(const char* cstring)
|
||||
|
||||
This function wraps `Toy_CreateRefStringLength`, by determining the length of the given `cstring` and passing it to the other function.
|
||||
|
||||
### Toy_RefString* Toy_createRefStringLength(const char* cstring, size_t length)
|
||||
|
||||
This function returns a new `Toy_RefString`, containing a copy of `cstring`, or `NULL` on error.
|
||||
|
||||
This function also sets the returned refstring's reference counter to 1.
|
||||
|
||||
### void Toy_deleteRefString(Toy_RefString* refString)
|
||||
|
||||
This function reduces the `refString`'s reference counter by 1 and, if it reaches 0, frees the memory.
|
||||
|
||||
### int Toy_countRefString(Toy_RefString* refString)
|
||||
|
||||
This function returns the total number of references to `refString`, for debugging.
|
||||
|
||||
### size_t Toy_lengthRefString(Toy_RefString* refString)
|
||||
|
||||
This function returns the length of the underlying cstring of `refString`.
|
||||
|
||||
### Toy_RefString* Toy_copyRefString(Toy_RefString* refString)
|
||||
|
||||
This function increases the reference counter of `refString` by 1, before returning the given pointer.
|
||||
|
||||
### Toy_RefString* Toy_deepCopyRefString(Toy_RefString* refString)
|
||||
|
||||
This function behaves identically to `Toy_copyRefString`, except that it explicitly preforms a deep copy of the internal memory. Using this function should be done carefully, as it incurs a performance penalty that negates the benefit of this module.
|
||||
|
||||
### const char* Toy_toCString(Toy_RefString* refString)
|
||||
|
||||
This function exposes the interal cstring of `refString`. Only use this function when dealing with external APIs.
|
||||
|
||||
### bool Toy_equalsRefString(Toy_RefString* lhs, Toy_RefString* rhs)
|
||||
|
||||
This function returns true when the two refstrings are either the same refstring, or contain the same value. Otherwise it returns false.
|
||||
|
||||
### bool Toy_equalsRefStringCString(Toy_RefString* lhs, char* cstring)
|
||||
|
||||
This function returns true when the `refString` contains the same value as the `cstring`. Otherwise it returns false.
|
||||
|
||||
|
||||
# toy_refstring.h
|
||||
|
||||
This header defines the structure `Toy_RefString`, as well as all of the related utilities.
|
||||
|
||||
[refstring](https://github.com/Ratstail91/refstring) is a stand-alone utility written to reduce the amount of memory manipulation used within Toy. It was independantly written and tested, before being incorporated into Toy proper. As such it has it's own memory management API, which by default is tied into Toy's [core memory API](toy_memory_h.md).
|
||||
|
||||
Instances of `Toy_RefString` are reference counted - that is, rather than copying an existing string in memory, a pointer to the refstring is returned, and the internal reference counter is increased by 1. When the pointer is no longer needed, `Toy_DeleteRefString` can be called; this will decrement the internal reference counter by 1, and only free it when it reaches 0. This has multiple benefits, when used correctly:
|
||||
|
||||
* Reduced memory usage
|
||||
* Faster program execution
|
||||
|
||||
This module reserves the right to instead preform a deep copy when it sees fit (this is for future debugging purposes).
|
||||
|
||||
## Defined Interfaces
|
||||
|
||||
### typedef void* (*Toy_RefStringAllocatorFn)(void* pointer, size_t oldSize, size_t newSize)
|
||||
|
||||
This interface conforms to Toy's memory API, and generally shouldn't be used without a good reason.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### void Toy_setRefStringAllocatorFn(Toy_RefStringAllocatorFn)
|
||||
|
||||
This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used without a good reason.
|
||||
|
||||
### Toy_RefString* Toy_createRefString(const char* cstring)
|
||||
|
||||
This function wraps `Toy_CreateRefStringLength`, by determining the length of the given `cstring` and passing it to the other function.
|
||||
|
||||
### Toy_RefString* Toy_createRefStringLength(const char* cstring, size_t length)
|
||||
|
||||
This function returns a new `Toy_RefString`, containing a copy of `cstring`, or `NULL` on error.
|
||||
|
||||
This function also sets the returned refstring's reference counter to 1.
|
||||
|
||||
### void Toy_deleteRefString(Toy_RefString* refString)
|
||||
|
||||
This function reduces the `refString`'s reference counter by 1 and, if it reaches 0, frees the memory.
|
||||
|
||||
### int Toy_countRefString(Toy_RefString* refString)
|
||||
|
||||
This function returns the total number of references to `refString`, for debugging.
|
||||
|
||||
### size_t Toy_lengthRefString(Toy_RefString* refString)
|
||||
|
||||
This function returns the length of the underlying cstring of `refString`.
|
||||
|
||||
### Toy_RefString* Toy_copyRefString(Toy_RefString* refString)
|
||||
|
||||
This function increases the reference counter of `refString` by 1, before returning the given pointer.
|
||||
|
||||
This function reserves the right to create a deep copy where needed.
|
||||
|
||||
### Toy_RefString* Toy_deepCopyRefString(Toy_RefString* refString)
|
||||
|
||||
This function behaves identically to `Toy_copyRefString`, except that it explicitly forces a deep copy of the internal memory. Using this function should be done carefully, as it incurs a performance penalty that negates the benefit of this module.
|
||||
|
||||
### const char* Toy_toCString(Toy_RefString* refString)
|
||||
|
||||
This function exposes the interal cstring of `refString`. Only use this function when dealing with external APIs.
|
||||
|
||||
### bool Toy_equalsRefString(Toy_RefString* lhs, Toy_RefString* rhs)
|
||||
|
||||
This function returns true when the two refstrings are either the same refstring, or contain the same value. Otherwise it returns false.
|
||||
|
||||
### bool Toy_equalsRefStringCString(Toy_RefString* lhs, char* cstring)
|
||||
|
||||
This function returns true when the `refString` contains the same value as the `cstring`. Otherwise it returns false.
|
||||
|
||||
@@ -1,46 +1,50 @@
|
||||
# toy_scope.h
|
||||
|
||||
This header defines the `Toy_Scope` structure, which stores all of the variables used within a given block of code.
|
||||
|
||||
Scopes are arranged into a linked list of ancestors, each of which is reference counted. When a scope is popped off the end of the chain, every ancestor scope has it's reference counter reduced by 1 and, if any reach 0, they are freed.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### Toy_Scope* Toy_pushScope(Toy_Scope* scope)
|
||||
|
||||
This function creates a new `Toy_scope` with `scope` as it's ancestor, and returns it.
|
||||
|
||||
### Toy_Scope* Toy_popScope(Toy_Scope* scope)
|
||||
|
||||
This function frees the given `scope`, and returns it's ancestor.
|
||||
|
||||
### Toy_Scope* Toy_copyScope(Toy_Scope* original)
|
||||
|
||||
This function copies an existing scope, and returns the copy.
|
||||
|
||||
### bool Toy_declareScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal type)
|
||||
|
||||
This function declares a new variable `key` within `scope`, giving it the type of `type`.
|
||||
|
||||
This function returns true on success, otherwise it returns failure (such as if the given key already exists).
|
||||
|
||||
### bool Toy_isDelcaredScopeVariable(Toy_Scope* scope, Toy_Literal key)
|
||||
|
||||
This function checks to see if a given variable with the name `key` has been previously declared.
|
||||
|
||||
### bool Toy_setScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal value, bool constCheck)
|
||||
|
||||
This function sets an existing variable named `key` to the value of `value`. This function fails if `constCheck` is true and the given key's type has the constaant flag set. It also fails if the given key doesn't exist.
|
||||
|
||||
This function returns true on success, otherwise it returns false.
|
||||
|
||||
### bool Toy_getScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal* value)
|
||||
|
||||
This function sets the literal pointed to by `value` to equal the variable named `key`.
|
||||
|
||||
This function returns true on success, otherwise it returns false.
|
||||
|
||||
### Toy_Literal Toy_getScopeType(Toy_Scope* scope, Toy_Literal key)
|
||||
|
||||
This function returns a new `Toy_Literal` representing the type of the variable named `key`.
|
||||
|
||||
|
||||
# toy_scope.h
|
||||
|
||||
This header defines the scope structure, which stores all of the variables used within a given block of code.
|
||||
|
||||
Scopes are arranged into a linked list of ancestors, each of which is reference counted. When a scope is popped off the end of the chain, every ancestor scope has it's reference counter reduced by 1 and, if any reach 0, they are freed.
|
||||
|
||||
This is also where Toy's type system lives.
|
||||
|
||||
## Defined Functions
|
||||
|
||||
### Toy_Scope* Toy_pushScope(Toy_Scope* scope)
|
||||
|
||||
This function creates a new `Toy_scope` with `scope` as it's ancestor, and returns it.
|
||||
|
||||
### Toy_Scope* Toy_popScope(Toy_Scope* scope)
|
||||
|
||||
This function frees the given `scope`, and returns it's ancestor.
|
||||
|
||||
### Toy_Scope* Toy_copyScope(Toy_Scope* original)
|
||||
|
||||
This function copies an existing scope, and returns the copy.
|
||||
|
||||
This copies the internal dictionaries, so it can be memory intensive.
|
||||
|
||||
### bool Toy_declareScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal type)
|
||||
|
||||
This function declares a new variable `key` within `scope`, giving it the type of `type`.
|
||||
|
||||
This function returns true on success, otherwise it returns failure (such as if the given key already exists).
|
||||
|
||||
### bool Toy_isDelcaredScopeVariable(Toy_Scope* scope, Toy_Literal key)
|
||||
|
||||
This function checks to see if a given variable with the name `key` has been previously declared.
|
||||
|
||||
### bool Toy_setScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal value, bool constCheck)
|
||||
|
||||
This function sets an existing variable named `key` to the value of `value`. This function fails if `constCheck` is true and the given key's type has the constaant flag set. It also fails if the given key doesn't exist.
|
||||
|
||||
This function returns true on success, otherwise it returns false.
|
||||
|
||||
### bool Toy_getScopeVariable(Toy_Scope* scope, Toy_Literal key, Toy_Literal* value)
|
||||
|
||||
This function sets the literal pointed to by `value` to equal the variable named `key`.
|
||||
|
||||
This function returns true on success, otherwise it returns false.
|
||||
|
||||
### Toy_Literal Toy_getScopeType(Toy_Scope* scope, Toy_Literal key)
|
||||
|
||||
This function returns a new `Toy_Literal` representing the type of the variable named `key`.
|
||||
|
||||
Reference in New Issue
Block a user