diff --git a/README.md b/README.md index 7e7b753..65ab236 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ print tally(); //3 * [Types](types) * [Standard Library](standard-library) * [Timer Library](timer-library) +* [Runner Library](runner-library) * [Game Engine](game-engine) # Deep Dive diff --git a/runner-library.md b/runner-library.md new file mode 100644 index 0000000..2df810f --- /dev/null +++ b/runner-library.md @@ -0,0 +1,77 @@ +# Runner Library + +The runner library is used to execute one script from inside another. It also has functions that allow you to retrieve variables from the other script. + +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 + initDriveDictionary(); + + //create a pair of literals, the first for the drive name, the second for the path + Literal driveLiteral = TO_STRING_LITERAL(createRefString("scripts")); + Literal pathLiteral = TO_STRING_LITERAL(createRefString("C:/path/to/scripts")); + + //set these within the drive dictionary + setLiteralDictionary(getDriveDictionary(), driveLiteral, pathLiteral); + + //these literals are no longer needed + freeLiteral(driveLiteral); + freeLiteral(pathLiteral); + + //run the rest of your program + repl(); + + //clean up the drive dictionary when you're done + freeDriveDictionary(); + + return 0; +} +``` + +The runner library can usually be accessed with the `import` keyword: + +```toy +import runner; +``` + +## loadScript(path: string) + +This is used to load an external script into an opaque variable. + +This function does a lot of work: + +* It validates the file path using the drive syntax (see above) +* It reads in the source code of the script file +* It compiles the source script into bytecode +* It constructs and intializes an Interpreter +* It packages it all into an opaque variable and returns it + +## loadScriptBytecode(path: string) + +*Not Yet Implemented* + +## _runScript(self: opaque) + +This function executes an external script, which must first be loaded into an opaque variable with either `loadScript()` or `loadScriptBytecode()`. + +## _getScriptVar(self: opaque, name: string) + +This function retrieves a variable from the top level of a script's environment. + +## _callScriptFn(self: opaque, name: string, ...rest) + +This function retrieves a function from the top level of a script's environment, and calls it with `rest` as the argument list. + +## _resetScript(self: opaque) + +This function resets the script so that it is no longer in a "dirty" state, and can be re-run using `_runScript()`. + +## _freeScript(self: opaque) + +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. +