# knitout_interpreter.knitout_language package

## Submodules

- knitout_interpreter.knitout_language.Knitout_Context module
  - `process_knitout_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()`
- knitout_interpreter.knitout_language.Knitout_Parser module
  - `Knitout_Parser`
    - `Knitout_Parser.parse_knitout_to_instructions()`
  - `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

knitout_language: Parsing and grammar support for knitout files.

This module provides the parsing infrastructure for knitout files, including grammar definitions, parser actions, and execution context management. It handles the conversion from raw knitout text files into structured Python objects thatcan be executed on virtual knitting machines.

Key Components:

  - Knitout_Parser: Main parser class using Parglare for grammar-based parsing

  - parse_knitout: Convenience function for parsing knitout files or strings

  - Knitout_Context: Manages the state and context during knitout execution

  - knitout_actions: Parser action functions that convert grammar matches to objects

  - Grammar files: <knitout.pg> and <knitout.pgt> contain the formal grammar definition

Parsing Process:

  1. Raw knitout text is tokenized according to the grammar.

  2. Parser actions convert tokens into instruction objects.

  3. Context manager organizes instructions into executable sequences.

  4. Instructions can be executed on virtual knitting machines.

Example

Parse a knitout file:

    >>> from knitout_interpreter.knitout_language.Knitout_Parser import parse_knitout
    >>> instructions = parse_knitout("pattern.k", pattern_is_file=True)
    >>> print(f"Parsed {len(instructions)} instructions")

Use the parser directly for more control:

    >>> from knitout_interpreter.knitout_language.Knitout_Parser import Knitout_Parser
    >>> parser = Knitout_Parser(debug_parser=True)
    >>> instructions = parser.parse_knitout_to_instructions("knit + f1 1")

Manage execution context:

    >>> from knitout_interpreter.knitout_language.Knitout_Context import Knitout_Context
    >>> context = Knitout_Context()
    >>> instructions, machine, graph = context.process_knitout_file("pattern.k")

Grammar Support:

  The parsing is based on a formal grammar definition that supports: - All knitout v2 specification instructions - Header declarations (machine, gauge, yarn, carriers, position) - Comments and version specifications - Proper error handling and reporting

Submodule Organization:

  Knitout_Parser.py: Main parser implementation using Parglare Knitout_Context.py: Execution context and state management knitout_actions.py: Parser action functions for grammar reduction knitout.pg: Grammar file defining knitout language syntax knitout.pgt: Compiled grammar table (generated automatically)

Usage Patterns:
  Simple parsing (most common):

    from knitout_interpreter.knitout_language import parse_knitout

  Advanced parsing control:

    from knitout_interpreter.knitout_language import Knitout_Parser

  Execution context management:

    from knitout_interpreter.knitout_language import Knitout_Context

knitout_interpreter.knitout_language.parse_knitout(pattern, pattern_is_file=False, debug_parser=False, debug_parser_layout=False)

  Execute the parsing code for the parglare parser.

  This is a convenience function that creates a Knitout_Parser instance and parses the given pattern.

  Parameters:

    - pattern (str) – Either a file path or the knitout string to be parsed.

    - pattern_is_file (bool) – If True, treat pattern as a file path. Defaults to False.

    - debug_parser (bool) – Enable parser debugging. Defaults to False.

    - debug_parser_layout (bool) – Enable parser layout debugging. Defaults to False.

  Returns:

    List of knitout instructions created by parsing the given pattern.

  Raises:

    - parglare.exceptions.ParseError – If there’s an error parsing the knitout code.

    - FileNotFoundError – If the grammar file or input file cannot be found.

  Return type:

    list[Knitout_Line]

class knitout_interpreter.knitout_language.Knitout_Parser(debug_grammar=False, debug_parser=False, debug_parser_layout=False)

  Bases: `object`

  Parser for reading knitout using the parglare library.

  parse_knitout_to_instructions(pattern, pattern_is_file=False, reset_parser=True, debug_parser=False, debug_parser_layout=False)

    Parse knitout pattern into a list of instruction objects.

    Parameters:

      - pattern (str) – Either a file path or the knitout string to be parsed.

      - pattern_is_file (bool) – If True, treat pattern as a file path. Defaults to False.

      - reset_parser (bool) – Reset parser to have no prior input. Defaults to True.

      - debug_parser (bool) – Enable parser debugging. Defaults to False.

      - debug_parser_layout (bool) – Enable parser layout debugging. Defaults to False.

    Returns:

      List of knitout instructions created by parsing the given pattern.

    Raises:

      parglare.exceptions.ParseError – If there’s an error parsing the knitout code.

    Return type:

      list[Knitout_Line]

class knitout_interpreter.knitout_language.Knitout_Context

  Bases: `object`

  Maintains information about the state of a knitting process as knitout instructions are executed.

  property version: int

    Get the knitout version of the current context.

    Returns:

      The knitout version number, defaults to 2 if no version is set.

  execute_header(header_declarations, comment_no_op_header=False)

    Update the machine state based on the given header values.

    Header declarations that do not change the current context can optionally be converted to comments.

    Parameters:

      - header_declarations (list[Knitout_Header_Line]) – The header lines to update based on.

      - comment_no_op_header (bool) – If True, no-op header declarations will be added to the instructions as comments. Defaults to False.

  execute_instructions(instructions)

    Execute the instruction set on the machine state defined by the current header.

    Parameters:

      instructions (list[Knitout_Line]) – Instructions to execute on the knitting machine.

  execute_knitout(version_line, header_declarations, instructions)

    Execute the given knitout organized by version, header, and instructions.

    Parameters:

      - version_line (Knitout_Version_Line) – The version of knitout to use.

      - header_declarations (list[Knitout_Header_Line]) – The header to define the knitout file.

      - instructions (list[Knitout_Instruction]) – The instructions to execute on the machine.

    Returns:

      - List of knitout instructions that were executed

      - Machine state after execution

      - Knit graph created by execution

    Return type:

      A tuple containing

  process_knitout_file(knitout_file_name)

    Parse and process a file of knitout code.

    Parameters:

      knitout_file_name (str) – File path containing knitout code to process.

    Returns:

      - List of executed knitout lines

      - Knitting machine state after execution

      - Knit graph formed by execution

    Return type:

      A tuple containing

  execute_knitout_instructions(codes)

    Execute given knitout instructions.

    Parameters:

      codes (list[Knitout_Line]) – List of knitout lines to execute.

    Returns:

      - List of executed knitout lines

      - Machine state after execution

      - Knit graph created by execution

    Return type:

      A tuple containing

knitout_interpreter.knitout_language.get_supported_versions()

  Get list of supported knitout specification versions.

  Returns:

    List of integer version numbers that this parser supports.

  Return type:

    list[int]