ml_switcheroo.core.mlir.parser
==============================

.. py:module:: ml_switcheroo.core.mlir.parser

.. autoapi-nested-parse::

   MLIR Recursive Descent Parser.

   This module parses text-based MLIR code into the CST object model defined in `nodes.py`.
   It is designed to preserve trivia (comments/whitespace) to support high-fidelity
   round-trip transformations.



Classes
-------

.. autoapisummary::

   ml_switcheroo.core.mlir.parser.Token
   ml_switcheroo.core.mlir.parser.Tokenizer
   ml_switcheroo.core.mlir.parser.MlirParser


Module Contents
---------------

.. py:class:: Token

   Represents a lexical token extracted from the source string.


   .. py:attribute:: kind
      :type:  str


   .. py:attribute:: text
      :type:  str


   .. py:attribute:: line
      :type:  int


   .. py:attribute:: col
      :type:  int


.. py:class:: Tokenizer(text: str)

   Lexical analyzer for MLIR syntax.

   Splits the input string into a stream of typed Tokens based on regex patterns.


   .. py:attribute:: PATTERN_DEFS


   .. py:attribute:: text


   .. py:method:: tokenize() -> Generator[Token, None, None]

      Yields tokens from the source text one by one.

      :Yields: *Token* -- The next lexical token.

      :raises ValueError: If an unrecognized character sequence is encountered.



.. py:class:: MlirParser(text: str)

   Parses a stream of MLIR tokens into a Concrete Syntax Tree.

   Implements recursive descent logic to handle Modules, Blocks, Operations,
   and Regions while preserving whitespace and comments (trivia) for accurate reproduction.


   .. py:attribute:: tokenizer


   .. py:attribute:: tokens


   .. py:attribute:: pos
      :value: 0



   .. py:attribute:: trivia_buffer
      :type:  List[ml_switcheroo.core.mlir.nodes.TriviaNode]
      :value: []



   .. py:method:: peek(offset: int = 0) -> Token

      Look ahead at a token without consuming it.

      :param offset: Number of tokens to look ahead. Defaults to 0 (current).
      :type offset: int

      :returns: The token at the lookahead position.
      :rtype: Token



   .. py:method:: consume() -> Token

      Consumes and returns the current token, advancing the pointer.

      :returns: The consumed token.
      :rtype: Token



   .. py:method:: match(kind: str) -> bool

      Checks if the current token matches the specified kind or text.

      :param kind: The token kind (e.g. TokenKind.VAL_ID) or specific symbol text (e.g. '{').
      :type kind: str

      :returns: True if the current token matches.
      :rtype: bool



   .. py:method:: expect(kind: str) -> Token

      Consume the current token if it matches kind, otherwise raise SyntaxError.

      :param kind: The expected token kind or text.
      :type kind: str

      :returns: The consumed token.
      :rtype: Token

      :raises SyntaxError: If the current token does not match the expectation.



   .. py:method:: parse() -> ml_switcheroo.core.mlir.nodes.ModuleNode

      Top-level parsing entry point.

      :returns: The root of the MLIR CST.
      :rtype: ModuleNode



   .. py:method:: parse_block(is_top_level: bool = False) -> ml_switcheroo.core.mlir.nodes.BlockNode

      Parses a Basic Block.

      A block consists of an optional label (with arguments) and a list of operations.

      :param is_top_level: If True, treats the input as an implicit top-level module block
                           which may not have a label or braces.
      :type is_top_level: bool

      :returns: The parsed block structure.
      :rtype: BlockNode

      :raises SyntaxError: If invalid tokens are encountered where an operation was expected.



   .. py:method:: parse_operation() -> Optional[ml_switcheroo.core.mlir.nodes.OperationNode]

      Parses a single MLIR Operation.

      Structure:
      `%results = "op.name"(%operands) {attributes} ({regions}) : type`

      :returns: The parsed operation, or None if no valid op start found.
      :rtype: Optional[OperationNode]

      :raises SyntaxError: If structural expectations (e.g. closing parens) are unmet.



   .. py:method:: parse_region() -> ml_switcheroo.core.mlir.nodes.RegionNode

      Parses a Region containing nested Blocks.

      Enclosed in curly braces `{ ... }`.

      :returns: The parsed region.
      :rtype: RegionNode