toy_interpreter.h File Reference

@???@ More...

#include <stdbool.h>
#include <stddef.h>
#include "toy_common.h"
#include "toy_literal.h"
#include "toy_literal_array.h"
#include "toy_literal_dictionary.h"
#include "toy_scope.h"

Go to the source code of this file.

Data Structures
struct	Toy_Interpreter

Typedefs
typedef struct Toy_Interpreter	Toy_Interpreter
	@???@

Functions
TOY_API bool	Toy_injectNativeFn (Toy_Interpreter *interpreter, const char *name, Toy_NativeFn func)
	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.
TOY_API bool	Toy_injectNativeHook (Toy_Interpreter *interpreter, const char *name, Toy_HookFn hook)
	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.
TOY_API bool	Toy_callLiteralFn (Toy_Interpreter *interpreter, Toy_Literal func, Toy_LiteralArray *arguments, Toy_LiteralArray *returns)
	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.
TOY_API bool	Toy_callFn (Toy_Interpreter *interpreter, const char *name, Toy_LiteralArray *arguments, Toy_LiteralArray *returns)
	Utility function that 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).
TOY_API 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: Toy_Literal foobarIdn = foobar; if (TOY_IS_IDENTIFIER(foobar) && Toy_parseIdentifierToValue(interpreter, &foobar)) { freeLiteral(foobarIdn); //remember to free the identifier }.
TOY_API 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: static void printWrapper(const char* output) { printf("%s\n", output); }.
TOY_API void	Toy_setInterpreterAssert (Toy_Interpreter *interpreter, Toy_PrintFn assertOutput)
	Sets the function called by the assert keyword on failure. By default, the following wrapper is used: static void assertWrapper(const char* output) { fprintf(stderr, "Assertion failure: %s\n", output); }.
TOY_API void	Toy_setInterpreterError (Toy_Interpreter *interpreter, Toy_PrintFn errorOutput)
	Sets the function called when an error occurs within the interpreter. By default, the following wrapper is used: static void errorWrapper(const char* output) { fprintf(stderr, "%s", output); //no newline }.
TOY_API void	Toy_initInterpreter (Toy_Interpreter *interpreter)
	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.
TOY_API void	Toy_runInterpreter (Toy_Interpreter *interpreter, const unsigned char *bytecode, size_t length)
	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.
TOY_API void	Toy_resetInterpreter (Toy_Interpreter *interpreter)
	Frees any environment that the scripts have built up, and generates a new one. It also injects several globally available functions:
TOY_API void	Toy_freeInterpreter (Toy_Interpreter *interpreter)
	Frees a Toy_Interpreter, clearing all of the memory used within. That interpreter is no longer valid for use, and must be re-initialized.

Detailed Description

@???@

Typedef Documentation

Toy_Interpreter

Toy_Interpreter

@???@

Function Documentation

Toy_callFn()

bool Toy_callFn	(	Toy_Interpreter *	interpreter,
		const char *	name,
		Toy_LiteralArray *	arguments,
		Toy_LiteralArray *	returns
	)

Utility function that 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).

Parameters

interpreter
name
arguments
returns

Returns

Toy_callLiteralFn()

bool Toy_callLiteralFn	(	Toy_Interpreter *	interpreter,
		Toy_Literal	func,
		Toy_LiteralArray *	arguments,
		Toy_LiteralArray *	returns
	)

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.

Parameters

interpreter
func
arguments
returns

Returns

Toy_freeInterpreter()

void Toy_freeInterpreter

(

Toy_Interpreter *

interpreter

)

Frees a Toy_Interpreter, clearing all of the memory used within. That interpreter is no longer valid for use, and must be re-initialized.

Parameters

interpreter

Toy_initInterpreter()

void Toy_initInterpreter

(

Toy_Interpreter *

interpreter

)

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.

Parameters

interpreter

Toy_injectNativeFn()

bool Toy_injectNativeFn	(	Toy_Interpreter *	interpreter,
		const char *	name,
		Toy_NativeFn	func
	)

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.

Parameters

interpreter
name
func

Returns

Toy_injectNativeHook()

bool Toy_injectNativeHook	(	Toy_Interpreter *	interpreter,
		const char *	name,
		Toy_HookFn	hook
	)

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.

Parameters

interpreter
name
hook

Returns

Toy_parseIdentifierToValue()

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: Toy_Literal foobarIdn = foobar; if (TOY_IS_IDENTIFIER(foobar) && Toy_parseIdentifierToValue(interpreter, &foobar)) { freeLiteral(foobarIdn); //remember to free the identifier }.

Parameters

interpreter
literalPtr

Returns

Toy_resetInterpreter()

void Toy_resetInterpreter

(

Toy_Interpreter *

interpreter

)

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

Parameters

interpreter

Toy_runInterpreter()

void Toy_runInterpreter	(	Toy_Interpreter *	interpreter,
		const unsigned char *	bytecode,
		size_t	length
	)

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.

Parameters

interpreter
bytecode
length

Toy_setInterpreterAssert()

void Toy_setInterpreterAssert	(	Toy_Interpreter *	interpreter,
		Toy_PrintFn	assertOutput
	)

Sets the function called by the assert keyword on failure. By default, the following wrapper is used: static void assertWrapper(const char* output) { fprintf(stderr, "Assertion failure: %s\n", output); }.

Parameters

interpreter
assertOutput

Toy_setInterpreterError()

void Toy_setInterpreterError	(	Toy_Interpreter *	interpreter,
		Toy_PrintFn	errorOutput
	)

Sets the function called when an error occurs within the interpreter. By default, the following wrapper is used: static void errorWrapper(const char* output) { fprintf(stderr, "%s", output); //no newline }.

Parameters

interpreter
errorOutput

Toy_setInterpreterPrint()

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: static void printWrapper(const char* output) { printf("%s\n", output); }.

Parameters

interpreter
printOutput