PhasorRT.h File Reference

#include <stdbool.h>
#include <stddef.h>

Include dependency graph for PhasorRT.h:

Go to the source code of this file.

Macros
#define	PHASOR_API

Functions
PHASOR_API const char *	getVersion ()
	Get the version string for Phasor VM.
PHASOR_API int	exec (void *state, const unsigned char *bytecode, size_t bytecodeSize, const char *moduleName, int argc, const char **argv)
	Executes pre-compiled Phasor bytecode.
PHASOR_API int	execFuncInt (void *state, const unsigned char *bytecode, size_t bytecodeSize, const char *moduleName, int argc, const char **argv, const char *functionName)
	Executes a function from pre-compiled Phasor bytecode, and casts return to an integer.
PHASOR_API const char *	execFuncString (void *state, const unsigned char *bytecode, size_t bytecodeSize, const char *moduleName, int argc, const char **argv, const char *functionName)
	Executes a function from pre-compiled Phasor bytecode, and casts return to an string.
PHASOR_API int	evaluatePHS (void *state, const char *script, const char *moduleName, const char *modulePath, bool verbose)
	Executes a Phasor Programming Language script.
PHASOR_API int	evaluatePUL (void *state, const char *script, const char *moduleName)
	Executes a Pulsar Scripting Language script.
PHASOR_API bool	compilePHS (const char *script, const char *moduleName, const char *modulePath, unsigned char *buffer, size_t bufferSize, size_t *outSize)
	Compiles a Phasor Programming Language script into Phasor VM bytecode.
PHASOR_API bool	compilePUL (const char *script, const char *moduleName, unsigned char *buffer, size_t bufferSize, size_t *outSize)
	Compiles a Pulsar Scripting Language script into Phasor VM bytecode.
PHASOR_API void *	createState ()
	Creates a new state instance.
PHASOR_API void	initStdLib (void *state)
	Register standard library to state instance.
PHASOR_API bool	freeState (void *state)
	Frees an existing state instance.
PHASOR_API bool	resetState (void *state, bool resetFunctions, bool resetVariables)
	Resets the state.

Macro Definition Documentation

PHASOR_API

#define PHASOR_API

Definition at line 42 of file PhasorRT.h.

Function Documentation

compilePHS()

PHASOR_API bool compilePHS	(	const char *	script,
		const char *	moduleName,
		const char *	modulePath,
		unsigned char *	buffer,
		size_t	bufferSize,
		size_t *	outSize )

Compiles a Phasor Programming Language script into Phasor VM bytecode.

Parameters

[in]	script	A string containing the Phasor source to compile.
[in]	moduleName	The name of the module, used for error reporting.
[in]	modulePath	An required path to the parent folder for the script, used for resolving compile time imports.
[out]	buffer	A pointer to a buffer where the compiled bytecode will be written. If null, the function will only calculate the required buffer size and return it via outSize.
[in]	bufferSize	The size of the provided buffer. This is ignored if buffer is null.
[out]	outSize	If buffer is null, this will be set to the required buffer size to hold the compiled bytecode. If buffer is not null, this will be set to the actual size of the compiled bytecode.

Returns

if buffer is null, returns true if compilation succeeded. if buffer is not null, returns true if compilation succeeded and buffer was valid and large enough to hold the compiled bytecode.

if bufferSize < data.size(), buffer will not be modified, however outSize will be set.

Definition at line 135 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

compilePUL()

PHASOR_API bool compilePUL	(	const char *	script,
		const char *	moduleName,
		unsigned char *	buffer,
		size_t	bufferSize,
		size_t *	outSize )

Compiles a Pulsar Scripting Language script into Phasor VM bytecode.

Parameters

[in]	script	A string containing the Pulsar source to compile.
[in]	moduleName	The name of the module, used for error reporting.
[out]	buffer	A pointer to a buffer where the compiled bytecode will be written. If null, the function will only calculate the required buffer size and return it via outSize.
[in]	bufferSize	The size of the provided buffer. This is ignored if buffer is null.
[out]	outSize	If buffer is null, this will be set to the required buffer size to hold the compiled bytecode. If buffer is not null, this will be set to the actual size of the compiled bytecode.

Returns

if buffer is null, returns true if compilation succeeded. if buffer is not null, returns true if compilation succeeded and buffer was valid and large enough to hold the compiled bytecode.

if bufferSize < data.size(), buffer will not be modified, however outSize will be set.

Definition at line 174 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

createState()

PHASOR_API void * createState

(

)

Creates a new state instance.

Returns

Pointer to the newly created state.

A state is a Phasor::VM object, refered to as State from a high level to avoid bad programming. Dependence on the internal structure of the VM class is not officially supported and will not work across compilers. This version of the C API is designed to work across compilers and outlive minor, potentially even major versions of the VM.

void *state = createState();
initStdLib(state);
 
const char *script = "using(\\\"stdio\\\"); puts(\\\"Hello, World!\\");";
 
size_t bytecodeSize = 0;
compilePHS(script, "example", "./", NULL, 0, &bytecodeSize);
 
unsigned char *bytecode = (unsigned char *)malloc(bytecodeSize);
compilePHS(script, "example", "./", bytecode, bytecodeSize, &bytecodeSize);
 
const char *argv[] = { "program", "script", "arg1", "arg2" };
int result = exec(state, bytecode, bytecodeSize, "example", 4, argv);
 
free(bytecode);
freeState(state);

Definition at line 208 of file NativeRuntime_library.cpp.

evaluatePHS()

PHASOR_API int evaluatePHS	(	void *	state,
		const char *	script,
		const char *	moduleName,
		const char *	modulePath,
		bool	verbose )

Executes a Phasor Programming Language script.

Parameters

state	A pointer to an state to execute the script within. If null, new state will be created and managed for you.
script	A string containing the Phasor source to compile and execute.
moduleName	The name of the module, used for error reporting.
modulePath	A required path to the parent folder for the script, used for resolving compile time imports.
verbose	Prints AST to stdout.

Returns

The exit code of the program given from script (-1 might be an unhandled exception in VM).

Definition at line 108 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

evaluatePUL()

PHASOR_API int evaluatePUL	(	void *	state,
		const char *	script,
		const char *	moduleName )

Executes a Pulsar Scripting Language script.

Parameters

state	A pointer to an state to execute the script within. If null, new state will be created and managed for you.
script	A string containing the Pulsar source to compile and execute.
moduleName	The name of the module, used for error reporting.

Returns

The exit code of the program given from script (-1 might be an unhandled exception in VM).

Definition at line 122 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

exec()

PHASOR_API int exec	(	void *	state,
		const unsigned char *	bytecode,
		size_t	bytecodeSize,
		const char *	moduleName,
		int	argc,
		const char **	argv )

Executes pre-compiled Phasor bytecode.

Parameters

state	A pointer to an state to execute the script within. If null, new state will be created and managed for you.
bytecode	An array of unsigned chars containing the Phasor bytecode.
bytecodeSize	The size of the bytecode array.
moduleName	The name of the module, used for error reporting.
argc	Argument count.
argv	Argument vector.

Returns

The exit code of the program given from script (-1 might be an unhandled exception in VM).

Definition at line 51 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

execFuncInt()

PHASOR_API int execFuncInt	(	void *	state,
		const unsigned char *	bytecode,
		size_t	bytecodeSize,
		const char *	moduleName,
		int	argc,
		const char **	argv,
		const char *	functionName )

Executes a function from pre-compiled Phasor bytecode, and casts return to an integer.

Parameters

state	A pointer to an state to execute the script within. If null, new state will be created and managed for you.
bytecode	An array of unsigned chars containing the Phasor bytecode.
bytecodeSize	The size of the bytecode array.
moduleName	The name of the module, used for error reporting.
argc	Argument count.
argv	Argument vector.
functionName	The name of the function to execute.

Returns

The return from the function call (-1 might be an unhandled exception in VM).

Definition at line 68 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

execFuncString()

PHASOR_API const char * execFuncString	(	void *	state,
		const unsigned char *	bytecode,
		size_t	bytecodeSize,
		const char *	moduleName,
		int	argc,
		const char **	argv,
		const char *	functionName )

Executes a function from pre-compiled Phasor bytecode, and casts return to an string.

Parameters

state	A pointer to an state to execute the script within. If null, new state will be created and managed for you.
bytecode	An array of unsigned chars containing the Phasor bytecode.
bytecodeSize	The size of the bytecode array.
moduleName	The name of the module, used for error reporting.
argc	Argument count.
argv	Argument vector.
functionName	The name of the function to execute.

Returns

The return from the function call, nullptr on error. This memory is cleared by the C++ runtime when you unload the DLL, and is overwritten after recalling this function. This DOES NOT use two pass for perf reasons. Copy the string to safe memory, or you will lose the data.

Definition at line 85 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

freeState()

PHASOR_API bool freeState

(

void *

state

)

Frees an existing state instance.

Parameters

state

Pointer to state to free.

Returns

false if the data was seemingly invalid or null, true otherwise.

This function like any low level function could be potentially unsafe if given the wrong thing. Support will not be accepted in these scenarios. Do not call many times on the same pointer.

Definition at line 219 of file NativeRuntime_library.cpp.

Here is the caller graph for this function:

getVersion()

PHASOR_API const char * getVersion

(

)

Get the version string for Phasor VM.

Returns

The version string.

Definition at line 46 of file NativeRuntime_library.cpp.

initStdLib()

PHASOR_API void initStdLib

(

void *

state

)

Register standard library to state instance.

Parameters

state

Pointer to state.

Registers standard library functions to a State instance.

Definition at line 214 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

resetState()

PHASOR_API bool resetState	(	void *	state,
		bool	resetFunctions,
		bool	resetVariables )

Resets the state.

Parameters

state	Pointer to the state to reset.
resetFunctions	Reset functions if set to true.
resetVariables	Reset variables if set to true.

This will always clear the stack, reset the PC, and clear bytecode.

Definition at line 228 of file NativeRuntime_library.cpp.

Here is the call graph for this function:

Here is the caller graph for this function: