# knitout_interpreter package

## Subpackages

- knitout_interpreter.knitout_execution_structures package
  - Submodules
    - knitout_interpreter.knitout_execution_structures.Carriage_Pass module
      - `Carriage_Pass`
  - Module contents
    - `Carriage_Pass`
      - `Carriage_Pass.instruction_set()`
      - `Carriage_Pass.rightward_sorted_needles()`
      - `Carriage_Pass.leftward_sorted_needles()`
      - `Carriage_Pass.sorted_needles()`
      - `Carriage_Pass.instructions_by_needles()`
      - `Carriage_Pass.carriage_pass_range()`
      - `Carriage_Pass.rack_instruction()`
      - `Carriage_Pass.direction`
      - `Carriage_Pass.needles`
      - `Carriage_Pass.first_instruction`
      - `Carriage_Pass.last_instruction`
      - `Carriage_Pass.last_needle`
      - `Carriage_Pass.contains_instruction_type()`
      - `Carriage_Pass.add_instruction()`
      - `Carriage_Pass.compatible_with_pass_type()`
      - `Carriage_Pass.can_add_instruction()`
      - `Carriage_Pass.can_merge_pass()`
      - `Carriage_Pass.merge_carriage_pass()`
      - `Carriage_Pass.execute()`
      - `Carriage_Pass.__str__()`
      - `Carriage_Pass.__list__()`
      - `Carriage_Pass.__len__()`
      - `Carriage_Pass.__repr__()`
      - `Carriage_Pass.__iter__()`
      - `Carriage_Pass.__getitem__()`
      - `Carriage_Pass.__hash__()`
- knitout_interpreter.knitout_language package
  - Submodules
    - knitout_interpreter.knitout_language.Knitout_Context module
      - `process_knitout_instructions()`
      - `Knitout_Context`
    - knitout_interpreter.knitout_language.Knitout_Parser module
      - `Knitout_Parser`
      - `parse_knitout()`
    - knitout_interpreter.knitout_language.knitout_actions module
      - `comment()`
      - `code_line()`
      - `magic_string()`
      - `header_line()`
      - `machine_op()`
      - `gauge_op()`
      - `yarn_op()`
      - `carriers_op()`
      - `position_op()`
      - `in_op()`
      - `inhook_op()`
      - `releasehook_op()`
      - `out_op()`
      - `outhook_op()`
      - `rack_op()`
      - `knit_op()`
      - `tuck_op()`
      - `miss_op()`
      - `kick_op()`
      - `split_op()`
      - `drop_op()`
      - `xfer_op()`
      - `pause_op()`
      - `identifier()`
      - `float_exp()`
      - `int_exp()`
      - `needle_id()`
      - `carrier_set()`
  - Module contents
    - `parse_knitout()`
    - `Knitout_Parser`
      - `Knitout_Parser.parse_knitout_to_instructions()`
    - `Knitout_Context`
      - `Knitout_Context.version`
      - `Knitout_Context.execute_header()`
      - `Knitout_Context.execute_instructions()`
      - `Knitout_Context.execute_knitout()`
      - `Knitout_Context.process_knitout_file()`
      - `Knitout_Context.execute_knitout_instructions()`
    - `get_supported_versions()`
- knitout_interpreter.knitout_operations package
  - Submodules
    - knitout_interpreter.knitout_operations.Header_Line module
      - `Knitout_Header_Line_Type`
      - `Knitout_Header_Line`
      - `Machine_Header_Line`
      - `Gauge_Header_Line`
      - `Position_Header_Line`
      - `Yarn_Header_Line`
      - `Carriers_Header_Line`
      - `Knitting_Machine_Header`
      - `get_machine_header()`
    - knitout_interpreter.knitout_operations.Knitout_Line module
      - `Knitout_Line`
      - `Knitout_Version_Line`
      - `Knitout_Comment_Line`
    - knitout_interpreter.knitout_operations.Pause_Instruction module
      - `Pause_Instruction`
    - knitout_interpreter.knitout_operations.Rack_Instruction module
      - `Rack_Instruction`
    - knitout_interpreter.knitout_operations.carrier_instructions module
      - `Yarn_Carrier_Instruction`
      - `Hook_Instruction`
      - `In_Instruction`
      - `Inhook_Instruction`
      - `Releasehook_Instruction`
      - `Out_Instruction`
      - `Outhook_Instruction`
    - knitout_interpreter.knitout_operations.kick_instruction module
      - `Kick_Instruction`
    - knitout_interpreter.knitout_operations.knitout_instruction module
      - `Knitout_Instruction_Type`
      - `Knitout_Instruction`
    - knitout_interpreter.knitout_operations.knitout_instruction_factory module
      - `build_instruction()`
    - knitout_interpreter.knitout_operations.needle_instructions module
      - `Needle_Instruction`
      - `Loop_Making_Instruction`
      - `Knit_Instruction`
      - `Tuck_Instruction`
      - `Split_Instruction`
      - `Drop_Instruction`
      - `Xfer_Instruction`
      - `Miss_Instruction`
  - Module contents
    - `Knit_Instruction`
      - `Knit_Instruction.execute()`
      - `Knit_Instruction.execute_knit()`
    - `Tuck_Instruction`
      - `Tuck_Instruction.execute()`
      - `Tuck_Instruction.execute_tuck()`
    - `Split_Instruction`
      - `Split_Instruction.execute()`
      - `Split_Instruction.execute_split()`
    - `Drop_Instruction`
      - `Drop_Instruction.execute()`
      - `Drop_Instruction.execute_Drop()`
    - `Xfer_Instruction`
      - `Xfer_Instruction.add_loop_crossing()`
      - `Xfer_Instruction.execute()`
      - `Xfer_Instruction.execute_xfer()`
    - `Miss_Instruction`
      - `Miss_Instruction.execute()`
      - `Miss_Instruction.execute_miss()`
    - `Kick_Instruction`
      - `Kick_Instruction.position`
      - `Kick_Instruction.no_carriers`
      - `Kick_Instruction.execute()`
      - `Kick_Instruction.execute_kick()`
    - `In_Instruction`
      - `In_Instruction.execute()`
      - `In_Instruction.execute_in()`
    - `Out_Instruction`
      - `Out_Instruction.execute()`
      - `Out_Instruction.execute_out()`
    - `Inhook_Instruction`
      - `Inhook_Instruction.execute()`
      - `Inhook_Instruction.execute_inhook()`
    - `Outhook_Instruction`
      - `Outhook_Instruction.execute()`
      - `Outhook_Instruction.execute_outhook()`
    - `Releasehook_Instruction`
      - `Releasehook_Instruction.preferred_release_direction`
      - `Releasehook_Instruction.execute()`
      - `Releasehook_Instruction.execute_releasehook()`
    - `Rack_Instruction`
      - `Rack_Instruction.rack`
      - `Rack_Instruction.all_needle_rack`
      - `Rack_Instruction.rack_value`
      - `Rack_Instruction.__str__()`
      - `Rack_Instruction.execute()`
      - `Rack_Instruction.rack_instruction_from_int_specification()`
      - `Rack_Instruction.execute_rack()`
    - `Pause_Instruction`
      - `Pause_Instruction.execute()`
      - `Pause_Instruction.execute_pause()`
    - `Machine_Header_Line`
      - `Machine_Header_Line.updates_machine_state()`
      - `Machine_Header_Line.execute()`
    - `Gauge_Header_Line`
      - `Gauge_Header_Line.updates_machine_state()`
      - `Gauge_Header_Line.execute()`
    - `Yarn_Header_Line`
      - `Yarn_Header_Line.updates_machine_state()`
      - `Yarn_Header_Line.execute()`
    - `Carriers_Header_Line`
      - `Carriers_Header_Line.updates_machine_state()`
      - `Carriers_Header_Line.execute()`
    - `Position_Header_Line`
      - `Position_Header_Line.updates_machine_state()`
      - `Position_Header_Line.execute()`
    - `Knitout_Header_Line_Type`
      - `Knitout_Header_Line_Type.Machine`
      - `Knitout_Header_Line_Type.Gauge`
      - `Knitout_Header_Line_Type.Yarn`
      - `Knitout_Header_Line_Type.Position`
      - `Knitout_Header_Line_Type.Carriers`
    - `Knitting_Machine_Header`
      - `Knitting_Machine_Header.update_header()`
      - `Knitting_Machine_Header.set_header_by_specification()`
      - `Knitting_Machine_Header.get_header_lines()`
    - `get_machine_header()`
    - `Knitout_Instruction_Type`
      - `Knitout_Instruction_Type.In`
      - `Knitout_Instruction_Type.Inhook`
      - `Knitout_Instruction_Type.Releasehook`
      - `Knitout_Instruction_Type.Out`
      - `Knitout_Instruction_Type.Outhook`
      - `Knitout_Instruction_Type.Stitch`
      - `Knitout_Instruction_Type.Rack`
      - `Knitout_Instruction_Type.Knit`
      - `Knitout_Instruction_Type.Tuck`
      - `Knitout_Instruction_Type.Split`
      - `Knitout_Instruction_Type.Drop`
      - `Knitout_Instruction_Type.Xfer`
      - `Knitout_Instruction_Type.Miss`
      - `Knitout_Instruction_Type.Kick`
      - `Knitout_Instruction_Type.Pause`
      - `Knitout_Instruction_Type.get_instruction()`
      - `Knitout_Instruction_Type.is_carrier_instruction`
      - `Knitout_Instruction_Type.is_needle_instruction`
      - `Knitout_Instruction_Type.in_knitting_pass`
      - `Knitout_Instruction_Type.all_needle_instruction`
      - `Knitout_Instruction_Type.directed_pass`
      - `Knitout_Instruction_Type.requires_carrier`
      - `Knitout_Instruction_Type.requires_second_needle`
      - `Knitout_Instruction_Type.allow_sliders`
      - `Knitout_Instruction_Type.compatible_pass()`
    - `Knitout_Comment_Line`
      - `Knitout_Comment_Line.execute()`
    - `Knitout_Version_Line`

## Submodules

- knitout_interpreter.knitout_execution module
  - `Knitout_Executer`
    - `Knitout_Executer.version_line`
    - `Knitout_Executer.execution_time`
    - `Knitout_Executer.left_most_position`
    - `Knitout_Executer.right_most_position`
    - `Knitout_Executer.resulting_knit_graph`
    - `Knitout_Executer.carriage_passes`
    - `Knitout_Executer.test_and_organize_instructions()`
    - `Knitout_Executer.write_executed_instructions()`
- knitout_interpreter.run_knitout module
  - `run_knitout()`

## Module contents

knitout_interpreter: A comprehensive library for interpreting knitout files.

This package provides tools for parsing, validating, and executing knitout files used to control automatic V-Bed knitting machines. It includes support for the complete Knitout specification v2 created by McCann et al.

The library bridges the gap between high-level knitting pattern descriptions and machine-level execution, providing comprehensive analysis and simulation capabilities.

Core Functionality:

  - run_knitout(): Simple function to parse and execute knitout files

  - Knitout_Executer: Advanced class for detailed analysis and execution control

For specialized functionality, import from submodules:

  - knitout_interpreter.knitout_operations: Individual instruction types

  - knitout_interpreter.knitout_language: Parsing and grammar support

  - knitout_interpreter.knitout_execution_structures: Execution data structures

Example

Basic usage - execute a knitout file:

    >>> from knitout_interpreter.run_knitout import run_knitout
    >>> instructions, machine, graph = run_knitout("pattern.k")
    >>> print(f"Executed {len(instructions)} instructions")

Advanced analysis with detailed control:

    >>> from knitout_interpreter import Knitout_Executer
    >>> from knitout_interpreter.knitout_language.Knitout_Parser import parse_knitout
    >>> from virtual_knitting_machine.Knitting_Machine import Knitting_Machine
    >>>
    >>> instructions = parse_knitout("pattern.k", pattern_is_file=True)
    >>> executer = Knitout_Executer(instructions, Knitting_Machine())
    >>> print(f"Execution time: {executer.execution_time} carriage passes")
    >>> print(f"Width required: {executer.left_most_position} to {executer.right_most_position}")

knitout_interpreter.run_knitout(knitout_file_name)

  Execute knitout instructions from a given file.

  This function provides a convenient interface for processing a knitout file through the knitout interpreter, returning the executed instructions and resulting machine state and knit graph.

  Parameters:

    knitout_file_name (str) – Path to the file that contains knitout instructions.

  Returns:

    A 3-element tuple containing the executed instructions, final machine state, and knit graph. The first element is a list of Knitout_Line objects representing all processed instructions. The second element is a Knitting_Machine object containing the final state of the virtual knitting machine after execution. The third element is a Knit_Graph object representing the resulting fabric structure formed by the knitting operations.

  Return type:

    tuple

  Example

  Basic usage:

      instructions, machine, graph = run_knitout("pattern.k")
      print(f"Executed {len(instructions)} instructions")
      print(f"Machine has {len(machine.needle_beds)} needle beds")
      print(f"Graph contains {graph.node_count} nodes")

  Note

  The knitout file must be a valid knitout format file with proper headers and instructions.

  Raises:

    - FileNotFoundError – If the specified knitout file cannot be found.

    - ValueError – If the knitout file contains invalid syntax or instructions.

class knitout_interpreter.Knitout_Executer(instructions, knitting_machine, accepted_error_types=None, knitout_version=2)

  Bases: `object`

  A class used to execute a set of knitout instructions on a virtual knitting machine.

  property version_line: Knitout_Version_Line

    Get the version line for the executed knitout.

    Returns:

      The version line for the executed knitout.

  property execution_time: int

    Get the execution time as measured by carriage passes.

    Returns:

      Count of carriage passes in process as a measure of knitting time.

  property left_most_position: int | None

    Get the leftmost needle position used in execution.

    Returns:

      The position of the left most needle used in execution, or None if no needles were used.

  property right_most_position: int | None

    Get the rightmost needle position used in execution.

    Returns:

      The position of the right most needle used in the execution, or None if no needles were used.

  property resulting_knit_graph: Knit_Graph

    Get the knit graph resulting from instruction execution.

    Returns:

      Knit Graph that results from execution of these instructions.

  property carriage_passes: list[Carriage_Pass]

    Get the carriage passes from this execution.

    Returns:

      The carriage passes resulting from this execution in execution order.

  test_and_organize_instructions(accepted_error_types=None)

    Test the given execution and organize the instructions in the class structure.

    This method processes all instructions, organizing them into carriage passes and handling any errors that occur during execution.

    Parameters:

      accepted_error_types (list | None) – A list of exceptions that instructions may throw that can be resolved by commenting them out. Defaults to None.

  write_executed_instructions(filename)

    Write a file with the organized knitout instructions.

    Parameters:

      filename (str) – The file path to write the executed instructions to.