:py:mod:`raesl.compile.state_machine`
=====================================

.. py:module:: raesl.compile.state_machine

.. autoapi-nested-parse::

   State machine classes to describe an allowed sequences of tokens.

   A state machine is a DFA (deterministic finite automaton, always at most one
   edge that matches). An edge is associated with a matched token, locations are
   decision points between tokens.

   An edge may tag occurrences of tokens to simplify extraction of relevant
   information for future compiler phases. A location may record matching of
   a valid sequence of tokens by accepting.



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

Classes
~~~~~~~

.. autoapisummary::

   raesl.compile.state_machine.Location
   raesl.compile.state_machine.Edge
   raesl.compile.state_machine.StateMachine
   raesl.compile.state_machine.MatchResult




.. py:class:: Location(name: str, accept: Optional[str] = None)


   Location in a state machine.

   :param accept: Name of the rule that could be accepted at this location.
                  If None, no such rule exists.
   :param name: Name of the location, mostly for identifying purposes.

   .. attribute:: out_edges

      Outgoing edges, initially empty.


.. py:class:: Edge(dest: Location, tok_type: str, tag_name: Optional[str] = None)


   Edge to a next location.

   :param dest: Destination of the edge.
   :param tok_type: The value of the 'tok_type' attribute of a token that can trigger
                    this transition.
   :param tag_name: If not None, the name to use for recording the transition in the
                    state machine.


.. py:class:: StateMachine(name: str)


   State machine containing locations and edges.

   Note that it only stores the initial location, all other locations and edges
   are reachable from it.

   :param name: Name of the state machine, also the name of the matched sequence.

   .. attribute:: initial_loc

      Initial location of the state machine. Set after construction.

   .. py:method:: sort_edges()

      Sort edges of the state machine to get specific tokens checked first.


   .. py:method:: dump(fname: Optional[str] = None)

      Dump the state machine to a file in Graphviz format.

      :param fname: If not None, name of the file to write, else a filename is
                    constructed from the name of the state machine.


   .. py:method:: match(lexer: raesl.compile.scanner.Lexer) -> Optional[MatchResult]

      Try to match the machine against tokens from the scanner.

      :param lexer: Token stream to match. Instance is useless afterwards, make a copy
                    beforehand if you need it again.

      :returns: Result of the matching process.

      .. note:: This routine is currently only used for testing.


   .. py:method:: single_step(lexer: raesl.compile.scanner.Lexer, current_loc: Location, tags: Dict[str, List[raesl.compile.scanner.Token]]) -> Optional[Tuple[Location, raesl.compile.scanner.Token]]

      Try to perform a single step in the state machine.

      :param lexer: Token stream to match. Instance is modified in-place if a transition
                    is taken.
      :param current_loc: Location to use for finding edges to try.
      :param tags: Collected tags so far, may be updated in-place if transition was
                   performed.

      :returns: New location and the matching token if a transition could be performed,
                else None.



.. py:class:: MatchResult(accepted_name: Optional[str], accepted_tags: Dict[str, List[raesl.compile.scanner.Token]], lexer: raesl.compile.scanner.Lexer)


   Result data of a matching process in StateMachine.match().

   :param accepted_name: Acceptance name from the last visited accepting location.
   :param accepted_tags: Collected tag data at the point of accepting.
   :param lexer: Lexer at the time of the last fail or at the time of the last accept