From 75781efb3a18594f38d46406a75a6b89d02b073b Mon Sep 17 00:00:00 2001 From: Kayne Ruse Date: Wed, 15 Mar 2023 06:58:13 +1100 Subject: [PATCH] Added the drive system docs --- c-api/toy_drive_system_h.md | 50 +++++++++++++++++++++++++++++++ getting-started/runner-library.md | 33 +++----------------- index.md | 1 + 3 files changed, 55 insertions(+), 29 deletions(-) create mode 100644 c-api/toy_drive_system_h.md diff --git a/c-api/toy_drive_system_h.md b/c-api/toy_drive_system_h.md new file mode 100644 index 0000000..59222d9 --- /dev/null +++ b/c-api/toy_drive_system_h.md @@ -0,0 +1,50 @@ +# 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. + diff --git a/getting-started/runner-library.md b/getting-started/runner-library.md index b8a946f..8a02f23 100644 --- a/getting-started/runner-library.md +++ b/getting-started/runner-library.md @@ -4,35 +4,6 @@ The runner library is used to execute one script from inside another. It also ha The runner library has a concept called a "dirty" script - dirty scripts are those which have already been run, and whose variables can be accessed. Dirty scripts must be reset before it is run again. -When using this library, you must first initialize the "drives" that are available. A drive is a simple way to ensure that the user and any modders don't have access to the entire hard drive. To set up the drives, you must designate a name for each folder you wish to enable access to, like so: - -```c -//it's a good idea to place this early in the program's execution, where it will only be run once -int main(int argc, const char* argv[]) { - //the drive system uses a LiteralDictionary, which must be initialized with this - Toy_initDriveDictionary(); - - //create a pair of literals, the first for the drive name, the second for the path - Toy_Literal driveLiteral = TOY_TO_STRING_LITERAL(Toy_createRefString("scripts")); - Toy_Literal pathLiteral = TOY_TO_STRING_LITERAL(Toy_createRefString("C:/path/to/scripts")); - - //set these within the drive dictionary - Toy_setLiteralDictionary(Toy_getDriveDictionary(), driveLiteral, pathLiteral); - - //these literals are no longer needed - Toy_freeLiteral(driveLiteral); - Toy_freeLiteral(pathLiteral); - - //run the rest of your program - repl(); - - //clean up the drive dictionary when you're done - Toy_freeDriveDictionary(); - - return 0; -} -``` - The runner library can usually be accessed with the `import` keyword: ```toy @@ -83,3 +54,7 @@ This function resets the script so that it is no longer in a "dirty" state, and This function frees a script's resources, cleaning up any memory that is no longer needed. Failing to call this will result in a memory leak. +## checkScriptDirty(self: opaque) + +This function returns true of the script is "dirty", otherwise it returns false. + diff --git a/index.md b/index.md index 4b37742..0c76ff5 100644 --- a/index.md +++ b/index.md @@ -73,6 +73,7 @@ print tally(); //3 * [toy.h](c-api/toy_h.md) * [toy_common.h](c-api/toy_common_h.md) * [toy_compiler.h](c-api/toy_compiler_h.md) +* [toy_drive_system.h](c-api/toy_drive_system_h.md) * [toy_interpreter.h](c-api/toy_interpreter_h.md) * [toy_lexer.h](c-api/toy_lexer_h.md) * [toy_literal_array.h](c-api/toy_literal_array_h.md)