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

.. py:module:: raesl.compile.parser

.. autoapi-nested-parse::

   Parsing the Elephant Specification Language.



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

Classes
~~~~~~~

.. autoapisummary::

   raesl.compile.parser.LineMachineStepper



Functions
~~~~~~~~~

.. autoapisummary::

   raesl.compile.parser.parse_line
   raesl.compile.parser.parse_lexer
   raesl.compile.parser.parse_spec
   raesl.compile.parser.collect_locations



.. py:class:: LineMachineStepper(machine: raesl.compile.machine_files.builder.ProcessingStateMachine, lexer: raesl.compile.scanner.Lexer, dest_loc: raesl.compile.state_machine.Location)


   Class managing parsing of a line in ESL.

   :param machine: Line matching machine to use for recognizing the line.
   :param lexer: Lexer to use in the matching process.
   :param current_loc: Current location in the line machine.
   :param tags: Relevant data extracted from the text line during the parsing process.
   :param matched_tokens: Tokens used for matching the line thus far.
   :param dest_loc: New specification location if a match was found.

   .. py:method:: try_step() -> bool

      Try to match the next token.

      :returns: Whether progress was made.


   .. py:method:: is_accepting() -> bool

      Is the machine in an accepting location?


   .. py:method:: get_accept_name() -> str

      Get the acceptance name associated with the accepting location.

      :returns: Name of the accepted 'rule'.



.. py:function:: parse_line(spec_state: raesl.compile.state_machine.Location, lexer: raesl.compile.scanner.Lexer, builder: raesl.compile.typechecking.ast_builder.AstBuilder, diag_store: raesl.compile.diagnostics.DiagnosticStore) -> Tuple[Optional[raesl.compile.state_machine.Location], Optional[raesl.compile.scanner.Lexer]]

   Parse a text-line in ESL.

   For debugging line selection, set scanner.PARSER_DEBUG to True, which enables
   printing debug information to the std output. For best results, use a *small*
   input specification, output is quite verbose.

   :param spec_state: Location in the ESL language state machine.
   :param lexer: Lexer pointing at the start of the next line to match.
   :param builder: Class storing extracted parse data.
   :param diag_store: Storage for reported diagnostics.

   :returns: Next state in the ESL state machine unless successfully finished, next lexer to
             use if next step can be performed.


.. py:function:: parse_lexer(lexer: raesl.compile.scanner.Lexer, diag_store: Optional[raesl.compile.diagnostics.DiagnosticStore], builder: Optional[raesl.compile.typechecking.ast_builder.AstBuilder], doc_comments: Optional[List[raesl.compile.scanner.Token]]) -> Tuple[raesl.compile.diagnostics.DiagnosticStore, raesl.compile.typechecking.ast_builder.AstBuilder, List[raesl.compile.scanner.Token], bool]

   Parse an ESL lexer, storing collected information in the builder.

   :param lexer: Lexer pointing at the start of the specification text.
   :param diag_store: Diagnostic store if one already has been created.
   :param builder: Builder if one already has been created.
   :param doc_comments: Doc comments if any have been found yet.

   :returns: Diagnostic store instance.
             Builder instance.
             Found doc comments.
             Whether there has been an error.


.. py:function:: parse_spec(lexers: Iterable[raesl.compile.scanner.Lexer], diag_store: Optional[raesl.compile.diagnostics.DiagnosticStore] = None) -> Tuple[raesl.compile.diagnostics.DiagnosticStore, Optional[raesl.compile.ast.specification.Specification]]

   Parse an ESL specification, storing collected information in the builder.

   :param lexers: Lexers pointing at the start of their respective texts (e.g. per-file).

   :returns: The found diagnostics, and if successful, the type-checked output.


.. py:function:: collect_locations(spec_state: raesl.compile.state_machine.Location) -> List[raesl.compile.state_machine.Location]

   Collect the set reachable states from 'spec_state' without taking only 'epsilon'
   transitions.