REPY_FN Loops - C Loops Controlled By Python Scope

Macros
#define	REPY_FN_WHILE_CACHE(bytecode_identifier, py_expression)
	Constructs a while loop that uses a cached Python expression executed in the current scope.
#define	REPY_FN_FOREACH_CACHE(bytecode_identifier, var_name, py_expression)
	Constructs a for loop that iterates through a Python object in the current scope, similar to how a Pythonic for loop works.
#define	REPY_FN_FOR_CACHE(bytecode_identifier, py_init_statement, py_eval_expression, py_update_statement)
	Constructs a C style for loop, using cached Python code.

Detailed Description

Because code string parsing and execution requires contiguous, compilable strings, there is no good way to call back into mod code from within a for or while loop in Python code. As an alternative, this section provides an easy and performant way to use the Python scope to govern mod code for and while loops, and even allows mod code to iterate through a Python object using REPY_IteratorHelper.

Provides an easy and performant way to use the Python scope for mod code loops.

There are no non-CACHE variations of these macros, as simple, REPY_FN_EVAL_BOOL and REPY_FN_EVAL_CSTR_BOOL can be used as the conditions of for and while loops directly, and REPY_FN_EXEC, REPY_FN_EXEC_CSTR can be used for the initialized and iterator of a for loop. Nevertheless, the term CACHE is included in these macro names to indicate that purpose and behavior; the code strings given to these macros are only parsed once, and the bytecode stored for repeated evaluations.

Macro Definition Documentation

REPY_FN_FOR_CACHE

#define REPY_FN_FOR_CACHE	(		bytecode_identifier,
			py_init_statement,
			py_eval_expression,
			py_update_statement )

Value:

REPY_INLINE_COMPILE_CACHE_BLOCK("REPY_FN_FOR_CACHE", bytecode_identifier ## _init_statement, REPY_CODE_EXEC, py_init_statement); \
REPY_INLINE_COMPILE_CACHE_BLOCK("REPY_FN_FOR_CACHE", bytecode_identifier ## _eval_expression, REPY_CODE_EVAL, py_eval_expression); \
REPY_INLINE_COMPILE_CACHE_BLOCK("REPY_FN_FOR_CACHE", bytecode_identifier ## _update_statement, REPY_CODE_EXEC, py_update_statement); \
for ( \
    REPY_FN_EXEC(bytecode_identifier ## _init_statement); \
    REPY_FN_EVAL_BOOL(bytecode_identifier ## _eval_expression); \
    REPY_FN_EXEC(bytecode_identifier ## _update_statement) \
)

Constructs a C style for loop, using cached Python code.

While the various FOREACH macros iterate through a Python object in the way that a for loop does in Python, this macro iterates in the way that a for loop in C does, with an initialization statement, a continuation condition expression, and an update statement. The key is that, with this macro, each of these statements/expressions are Python code, evaluated in the current scope.

Parameters

bytecode_identifier	Used to construct the names for 3 static Python bytecode variables, needed by the three statements/expressions.
py_init_statement	The Python code to use as the initialization statement. Should be a NULL-terminated C-string such as a string literal.
py_init_statement	The Python code to use as the continuation condition expression. Should be a NULL-terminated C-string such as a string literal.
py_init_statement	The Python code to use as the update statement. Should be a NULL-terminated C-string such as a string literal.

REPY_FN_FOREACH_CACHE

#define REPY_FN_FOREACH_CACHE	(		bytecode_identifier,
			var_name,
			py_expression )

Value:

REPY_INLINE_COMPILE_CACHE_BLOCK("REPY_FN_FOREACH_CACHE", bytecode_identifier, REPY_CODE_EVAL, py_expression); \
for ( \
    REPY_IteratorHelper* bytecode_identifier ## _iter = REPY_DeferredCleanupHelper_AddIteratorHelper( \
        REPY_FN_AUTO_CLEANUP, \
        REPY_IteratorHelper_Create(REPY_MakeSUH(REPY_FN_EVAL(bytecode_identifier)), REPY_FN_LOCAL_SCOPE, var_name, false) \
    ); \
    REPY_IteratorHelper_Update(bytecode_identifier ## _iter);\
) \

Constructs a for loop that iterates through a Python object in the current scope, similar to how a Pythonic for loop works.

A Python expression is evaluated in the object to iterate through. This can be a literal, a variable, function call, or any other valid Python expression, so long as the result is iterable. Each iteration, the current object will be added to the local scope using the variable name of var_name.

Much like REPY_FOREACH, A REPY_IteratorHelper object is created to manage the iteration process. The variable name for this helper in the format of bytecode_handle_iter. In addition to being added to the scope, the current object of the loop can be accessed via REPY_IteratorHelper_BorrowCurrent, and the index of that object can be accessed via * REPY_IteratorHelper_GetIndex. See the REPY_IteratorHelper documentation for more information.

Unlike REPY_FOREACH, this macro uses the REPY_FN scope's REPY_DeferredCleanupHelper to handle cleanup. So you don't need to worry about handling that yourself.

Parameters

bytecode_identifier	The name for a static variable that will hold the Python bytecode handle once created.
var_name	Each iteration of the loop, the current loop object will be added to the local scope under this variable name. Should be a NULL-terminated C-string such as a string literal.
py_expression	A Pythonic expression that evaluates to the iterable object. Should be a NULL-terminated C-string such as a string literal. This code string will only be parsed and compiled once.

REPY_FN_WHILE_CACHE

#define REPY_FN_WHILE_CACHE	(		bytecode_identifier,
			py_expression )

Value:

REPY_INLINE_COMPILE_CACHE_BLOCK("REPY_FN_WHILE_CACHE", bytecode_identifier, REPY_CODE_EVAL, py_expression); \
while (REPY_FN_EVAL_BOOL(bytecode_identifier))

Constructs a while loop that uses a cached Python expression executed in the current scope.

The Python expression is cast to bool after evaluation.

Parameters

bytecode_identifier	The name for a static variable that will hold the Python bytecode handle once created.
py_expression	The Python code to evaluate as the loop condition. Should be a NULL-terminated C-string such as a string literal. This code string will only be parsed and compiled once.