knit_script.knit_script_interpreter.Knit_Script_Interpreter module

Interpreter processes knit-script into knitout instructions.

This module provides the main interpreter class for converting knit script patterns into knitout instructions. The interpreter handles parsing, context management, and execution of knit script code while maintaining machine state and generating the corresponding knitout output.

The interpreter supports debugging capabilities, variable injection, and error handling for robust knit script processing.

This module defines the Knit_Script_Interpreter class and supporting functionality.

class Knit_Script_Interpreter(debug_grammar=False, debug_parser=False, debug_parser_layout=False, context=None, starting_variables=None)

Bases: object

A class to manage interpretation of knit script files with parglare parser.

The Knit_Script_Interpreter serves as the main entry point for processing knit script patterns. It manages the parsing process, maintains execution context, handles variable injection, and coordinates the generation of knitout instructions.

The interpreter provides comprehensive error handling and debugging capabilities, making it suitable for both development and production use cases.

_parser

The underlying parser for knit script syntax.

Type:

Knit_Script_Parser

_knitscript_context

The execution context containing variables, machine state, and other runtime information.

Type:

Knit_Script_Context

Parameters:

• debug_grammar (bool)

• debug_parser (bool)

• debug_parser_layout (bool)

• context (None | Knit_Script_Context)

• starting_variables (None | dict[str, Any])

__init__(debug_grammar=False, debug_parser=False, debug_parser_layout=False, context=None, starting_variables=None)

Initialize the knit script interpreter.

Creates a new interpreter instance with the specified configuration options. The interpreter can be customized with debugging flags, a custom execution context, and initial variables.

Parameters:

• debug_grammar (bool, optional) – If True, provides full parglare output for grammar states during parsing. Useful for debugging grammar issues. Defaults to False.

• debug_parser (bool, optional) – If True, provides full parglare output for parsed file shift-reduce status. Useful for debugging parsing issues. Defaults to False.

• debug_parser_layout (bool, optional) – If True, provides layout information from the parser. Useful for debugging whitespace and indentation issues. Defaults to False.

• context (Knit_Script_Context, optional) – A pre-configured knit script context to use instead of creating a new one. If None, a new context will be created. Defaults to None.

• starting_variables (dict[str, Any], optional) – Initial variables to load into the knit script execution scope. These variables will be available for use within knit script patterns. Defaults to None.

Note

Debug flags should only be enabled during development as they produce verbose output that can impact performance.

parse(pattern, pattern_is_file=False)

Execute the parsing process for the given knit script pattern.

This method processes the input pattern through the parglare parser, converting the knit script syntax into an abstract syntax tree (AST) representation that can be executed by the interpreter.

Parameters:

• pattern (str) – Either a knit script string to be parsed directly, or a filename containing the knit script code to be parsed.

• pattern_is_file (bool, optional) – If True, treats the pattern parameter as a filename and reads the script from that file. If False, treats pattern as the actual knit script code. Defaults to False.

Returns:

A list of parsed statements representing the abstract syntax tree of the knit script. Each element corresponds to a top-level statement or expression in the script.

Return type:

list[Any]

Raises:

• FileNotFoundError – If pattern_is_file is True and the specified file cannot be found or accessed.

• ParseError – If the knit script contains syntax errors that prevent successful parsing.

write_knitout(pattern, out_file_name, pattern_is_file=False, reset_context=True, **python_variables)

Write pattern knitout instructions to the specified output file.

This is the main method for converting knit script patterns into knitout format. It handles the complete workflow: parsing, interpretation, execution, and file output generation.

The method processes the input pattern, executes all knit script instructions, generates the corresponding knitout commands, and writes them to the specified output file. It also returns the internal representations for further analysis.

Parameters:

• pattern (str) – The knit script pattern to convert. Can be either: - A filename containing knit script code (when pattern_is_file=True) - A string containing the actual knit script code (when pattern_is_file=False)

• out_file_name (str) – The path where the generated knitout file will be written. Convention is to use ‘.k’ extension for knitout files.

• pattern_is_file (bool, optional) – Determines how to interpret the pattern parameter. If True, reads from the specified file. If False, treats pattern as direct script code. Defaults to False.

• reset_context (bool, optional) – If True, resets the interpreter context to its initial state after processing. If False, preserves the context state for subsequent operations. Defaults to True.

• **python_variables (dict[str, Any]) – Additional keyword arguments that will be injected into the knit script execution scope as variables.

Returns:

A tuple containing:

• list[Knitout_Line]: The complete sequence of knitout instructions generated from the pattern.

• Knit_Graph: The knit graph representation showing the structure and relationships of all stitches in the pattern.

• Knitting_Machine: The final state of the virtual knitting machine after executing all pattern instructions.

Return type:

tuple[list[Knitout_Line], Knit_Graph, Knitting_Machine]

Raises:

• FileNotFoundError – If pattern_is_file is True and the pattern file cannot be found.

• Knit_Script_Exception – If the knit script contains semantic errors or invalid operations.

• Knitting_Machine_Exception – If machine operations fail due to invalid states or impossible operations.

• AssertionError – If assertions within the knit script fail.

Note

If an error occurs during processing, an error.k file will be generated containing any knitout instructions that were successfully processed before the error, along with error comments.

knit_script_evaluate_expression(exp)

Evaluate a knit script expression within the current context.

This method evaluates knit script expressions using the current interpreter context, including all available variables and state. It provides a way to evaluate expressions outside the normal script execution flow.

Parameters:

exp (Expression) – The knit script expression object to evaluate. This should be a properly parsed expression from the knit script abstract syntax tree.

Returns:

The result of evaluating the expression. The type depends on the expression being evaluated (e.g., int, str, list, etc.).

Return type:

Any