Code Compilation and Execution Functions

Functions that deal with the compiling and executing Python code from inside mod code. More...

Macros
#define	REPY_VL   REPY_VariadicLocals
	Shorthand for REPY_VariadicLocals.
#define	REPY_VL_SUH   REPY_VariadicLocals_SUH
	Shorthand for REPY_VariadicLocals_SUH.

Functions
REPY_Handle	REPY_Compile (REPY_Handle code, REPY_Handle identifier, REPY_Handle mode)
	Compile a Python code string into Python bytecode, using a REPY_Handle for the text.
REPY_Handle	REPY_CompileCStr (const char *code, const char *identifier, REPY_CodeMode mode)
	Compile a Python code string into Python bytecode, using a NULL-terminated C string for the code.
REPY_Handle	REPY_CompileCStrN (const char *code, REPY_u32 len, const char *identifier, REPY_CodeMode mode)
	Compile a Python code string into Python bytecode, using a C char array for the code.
REPY_bool	REPY_Exec (REPY_Handle code, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Execute Python code statements from a REPY_Handle. Optionally provide dict objects to serve as a scope.
REPY_bool	REPY_ExecCStr (const char *code, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Execute Python code from a NULL-terminated C string. Optionally provide dict objects to serve as a scope.
REPY_bool	REPY_ExecCStrN (const char *code, REPY_u32 len, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Execute Python code from a C char array. Optionally provide dict objects to serve as a scope.
REPY_Handle	REPY_Eval (REPY_Handle code, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Evaluate a Python code expression from a REPY_Handle. Optionally provide dict objects to serve as a scope.
REPY_Handle	REPY_EvalCStr (const char *code, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Evaluate a Python code expression from a NULL-terminated C string. Optionally provide dict objects to serve as a scope.
REPY_Handle	REPY_EvalCStrN (const char *code, REPY_u32 len, REPY_Handle global_scope_nullable, REPY_Handle local_scope_nullable)
	Evaluate a Python code expression from a C char array. Optionally provide dict objects to serve as a scope.
REPY_Handle	REPY_VariadicLocals (REPY_Handle dict_nullable_no_release, REPY_u32 size,...)
	Adds the Python object represented by a set of REPY_Handle handles to a dict, using the keys following the scheme _0, _1, _2, etc. These keys serve as valid Python variable names to be used in code strings.
REPY_Handle	REPY_VariadicLocals_SUH (REPY_Handle dict_nullable_no_release, REPY_u32 size,...)
	Adds the Python object represented by a set of REPY_handles to a dict, using the keys following the scheme _0, _1, _2, etc. These keys serve as valid Python variable names to be used in code strings. This function also marks the resulting handle as Single-Use.

Detailed Description

Functions that deal with the compiling and executing Python code from inside mod code.

Function Documentation

REPY_Compile()

REPY_Handle REPY_Compile	(	REPY_Handle	code,
		REPY_Handle	identifier,
		REPY_Handle	mode )

Compile a Python code string into Python bytecode, using a REPY_Handle for the text.

This function is generally analogous to Python's own compile function, and should work in all the same circumstances.

Parameters

code	The Python text object containing the code to compile. Python's compile function works accepts str, bytes, and bytearray.
identifier	A Python text object identifying where the code came from.
mode	A Python str identifying the type of code this is. Use "exec" for an executable statement or series of statements, "eval" for an expression, or "single" for a interactive REPL statement.

Returns

A handle to the resulting Python bytecode object. Will be REPY_NO_HANDLE if an error occured.

REPY_CompileCStr()

REPY_Handle REPY_CompileCStr	(	const char *	code,
		const char *	identifier,
		REPY_CodeMode	mode )

Compile a Python code string into Python bytecode, using a NULL-terminated C string for the code.

This function is generally analogous to Python's own compile function, and should work in all the same circumstances.

Parameters

code	A NULL-terminated C string of Python code to compile.
identifier	A NULL-terminated C string identifying where the code came from.
mode	The type of code this is. Use REPY_CODE_EXEC for an executable statement or series of statements, REPY_CODE_EVAL for an expression, or REPY_CODE_SINGLE for a interactive REPL statement.

Returns

A handle to the resulting Python bytecode object. Will be REPY_NO_HANDLE if an error occured.

REPY_CompileCStrN()

REPY_Handle REPY_CompileCStrN	(	const char *	code,
		REPY_u32	len,
		const char *	identifier,
		REPY_CodeMode	mode )

Compile a Python code string into Python bytecode, using a C char array for the code.

This function is generally analogous to Python's own compile function, and should work in all the same circumstances.

Parameters

code	A pointer to the beginning of the char array to compile.
len	The length of the char array to compile.
identifier	A NULL-terminated C string identifying where the code came from.
mode	The type of code this is. Use REPY_CODE_EXEC for an executable statement or series of statements, REPY_CODE_EVAL for an expression, or REPY_CODE_SINGLE for a interactive REPL statement.

Returns

A handle to the resulting Python bytecode object. Will be REPY_NO_HANDLE if an error occured.

REPY_Eval()

REPY_Handle REPY_Eval	(	REPY_Handle	code,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Evaluate a Python code expression from a REPY_Handle. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's eval function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

As this function can execute precompiled Python bytecode, this is the recommended function for evaluating Python expressions from the API.

Parameters

code	The Python expression to evaluate. A precompiled bytecode object is recommended for performance reasons, but a Python str, bytes, or bytearray object will also work.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

A handle for the resulting object. Will be REPY_NO_HANDLE if an error occured.

REPY_EvalCStr()

REPY_Handle REPY_EvalCStr	(	const char *	code,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Evaluate a Python code expression from a NULL-terminated C string. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's eval function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

This function is not recommended for most use-cases, since it must recompile the Python bytecode from the code string with each run.

Parameters

code	The Python expression to evaluate. Should be a NULL-terminated C string.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

A handle for the resulting object. Will be REPY_NO_HANDLE if an error occured.

REPY_EvalCStrN()

REPY_Handle REPY_EvalCStrN	(	const char *	code,
		REPY_u32	len,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Evaluate a Python code expression from a C char array. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's eval function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

This function is not recommended for most use-cases, since it must recompile the Python bytecode from the code string with each run.

Parameters

code	A pointer to the beginning of the char array expression to evaluate.
len	The length of the char array in bytes.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

A handle for the resulting object. Will be REPY_NO_HANDLE if an error occured.

REPY_Exec()

REPY_bool REPY_Exec	(	REPY_Handle	code,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Execute Python code statements from a REPY_Handle. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's exec function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

As this function can execute precompiled Python bytecode, this is the recommended function for executing Python statements from the API.

Parameters

code	The Python code to execute. A precompiled bytecode object is recommended for performance reasons, but a Python str, bytes, or bytearray object will also work.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

true if the code executed without error, false otherwise.

REPY_ExecCStr()

REPY_bool REPY_ExecCStr	(	const char *	code,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Execute Python code from a NULL-terminated C string. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's exec function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

This function is not recommended for most use-cases, since it must recompile the Python bytecode from the code string with each run.

Parameters

code	The Python code to execute. Should be a NULL-terminated C string.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

true if the code executed without error, false otherwise.

REPY_ExecCStrN()

REPY_bool REPY_ExecCStrN	(	const char *	code,
		REPY_u32	len,
		REPY_Handle	global_scope_nullable,
		REPY_Handle	local_scope_nullable )

Execute Python code from a C char array. Optionally provide dict objects to serve as a scope.

This function is generally analogous to Python's exec function, with the exception that calling directly from the API means that there is no Python stack frame to inherit a scope from when executing. Hence, this function will create it's own if no scope dict objects are provided.

This function is not recommended for most use-cases, since it must recompile the Python bytecode from the code string with each run.

Parameters

code	A pointer to the beginning of the char array code to execute.
len	The length of the char array in bytes.
global_scope_nullable	The global scope to execute code in. Use REPY_NO_OBJECT to execute in a new, temporary scope.
local_scope_nullable	The global scope to execute code in. Using REPY_NO_OBJECT will make the global and local scopes be the same.

Returns

true if the code executed without error, false otherwise.

REPY_VariadicLocals()

REPY_Handle REPY_VariadicLocals	(	REPY_Handle	dict_nullable_no_release,
		REPY_u32	size,
			... )

Adds the Python object represented by a set of REPY_Handle handles to a dict, using the keys following the scheme _0, _1, _2, etc. These keys serve as valid Python variable names to be used in code strings.

This is a convienience function for quick REPY_Exec and REPY_Eval statements where establishing a scope or managing a whole dict is inconvenient. These keys serve as valid Python variable names to be used in code strings.

This function has slightly different behavior depending on whether or not dict_nullable is a valid dictionary. If dict_nullable is REPY_NO_OBJECT, then a new dictionary will be created, and a new handle returned. Otherwise, the provided dict will have new key-value pairs added to it, and provided handle is returned (that is to say, no new handle is created). Be advised that this will cause issues if dict_nullable is Single-Use.

Parameters

dict_nullable_no_release	Should be either a valid REPY_Handle for a dictionary, or REPY_NO_OBJECT.
size	the number of Python objects to add to the dict
...	The Python objects to add to the dict.

Returns

A REPY_Handle for the resulting dict. Will be the same as dict_nullable if that argument was set to anything other than REPY_NO_OBJECT

REPY_VariadicLocals_SUH()

REPY_Handle REPY_VariadicLocals_SUH	(	REPY_Handle	dict_nullable_no_release,
		REPY_u32	size,
			... )

Adds the Python object represented by a set of REPY_handles to a dict, using the keys following the scheme _0, _1, _2, etc. These keys serve as valid Python variable names to be used in code strings. This function also marks the resulting handle as Single-Use.

This is a convienience function for quick REPY_Exec and REPY_Eval statements where establishing a scope or managing a whole dict is inconvenient. These keys serve as valid Python variable names to be used in code strings.

This function has slightly different behavior depending on whether or not dict_nullable_no_release is a valid dictionary. If dict_nullable is REPY_NO_OBJECT, then a new dictionary will be created, and a new handle returned. Otherwise, the provided dict will have new key-value pairs added to it, and provided handle is returned (that is to say, no new handle is created). Be advised that this will cause issues if dict_nullable is Single-Use.

Also important, because this function marks the returned REPY_Handle as single use, but can potentially return the same handle as it was given, the handle for dict_nullable will become Single-Use if it was previously permanent.

Parameters

dict_nullable_no_release	Should be either a valid REPY_Handle for a dictionary, or REPY_NO_OBJECT.
size	the number of Python objects to add to the dict
...	The Python objects to add to the dict.

Returns

A REPY_Handle for the resulting dict. Will be the same as dict_nullable if that argument was set to anything other than REPY_NO_OBJECT.