gcode_reader.preprocess
=======================

.. py:module:: gcode_reader.preprocess

.. autoapi-nested-parse::

   Pre-processes lines of G-code programs to a consistent key-value format.

   Terminology Definitions:
   - Line (Block): The RS-274/NGC language is based on lines of code. Each line (block) may include commands to a machining center to do several different things. Lines of code may be collected in a file to make a program.
   - Word: A letter other than N followed by a real value. A real value is some collection of characters that can be processed to come up with a number. A real value may be an explicit number (such as 341 or -0.8807), a parameter value, an expression, or a unary operation value. Definitions of these follow immediately. Processing characters to come up with a number is called “evaluating”. An explicit number evaluates to itself.
   - Parameter: A key-value pair
   - Expression: A combination of parameters, operators, and values that can be evaluated to produce a result. Expressions can be used to calculate values dynamically based on other variables or conditions.

   References:
   - https://fabricesalvaire.github.io/pythonic-gcode-machine/gcode-reference/rs-274/index.html#format-of-a-line
   - https://www.nist.gov/publications/nist-rs274ngc-interpreter-version-3



Functions
---------

.. autoapisummary::

   gcode_reader.preprocess.line_declares_parameters
   gcode_reader.preprocess.line_insert_function_expressions
   gcode_reader.preprocess.line_insert_generic_expressions
   gcode_reader.preprocess.line_insert_parameters
   gcode_reader.preprocess.line_is_modal_group
   gcode_reader.preprocess.replacement_function


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

.. py:function:: line_declares_parameters(line: str, named_parameters: dict = {}, flavor: dict = syntax.flavors['default'])

   Uses syntax definition to identify declaration of named parameters in line.

   :param line: line (block) from a G-code program
   :type line: str
   :param named_parameters: Named parameter definition
   :type named_parameters: dict
   :param flavor: Syntax definition for line. Defaults to syntax.flavors["default"].
   :type flavor: dict, optional

   :returns: Existence of parameter declaration, dictionary of parameters
   :rtype: (bool, dict)


.. py:function:: line_insert_function_expressions(line, flavor: dict = syntax.flavors['default'])

   Inserts the evaluation of a functional expression into the line, such as COS[213], recursively.
   :param line: line (block) for a G-code program
   :type line: str
   :param flavor: Syntax definition for line. Defaults to syntax.flavors["default"].
   :type flavor: dict, optional

   :returns: Modified line
   :rtype: str

   Reference:
       https://fabricesalvaire.github.io/pythonic-gcode-machine/gcode-reference/rs-274/index.html#expressions-and-binary-operations


.. py:function:: line_insert_generic_expressions(line: str, flavor: dict = syntax.flavors['default'])

   Inserts the evaluation of a generic expression into the line, such as [1+1], recursively.
   :param line: line (block) for a G-code program
   :type line: str
   :param flavor: Syntax definition for line. Defaults to syntax.flavors["default"].
   :type flavor: dict, optional

   :returns: Modified line
   :rtype: str

   Reference:
       https://fabricesalvaire.github.io/pythonic-gcode-machine/gcode-reference/rs-274/index.html#expressions-and-binary-operations


.. py:function:: line_insert_parameters(line: str, named_parameters: dict = {}, flavor: dict = syntax.flavors['default'])

   Uses syntax definition to identify named parameters in line. Replaces with values

   :param line: line (block) from a G-code program
   :type line: str
   :param named_parameters: Named parameter definition
   :type named_parameters: dict
   :param flavor: Syntax definition for line. Defaults to syntax.flavors["default"].
   :type flavor: dict, optional

   :returns: Modified line
   :rtype: str


.. py:function:: line_is_modal_group(line: str, flavor: dict = syntax.flavors['default'])

   Determines if G-code line is a modal group. Modal commands are arranged in sets such as "G7 G18 G19"

   :param line: Un-processed line (block) from a G-code program
   :type line: str
   :param flavor: Syntax definition for line. Defaults to syntax.flavors["default"].
   :type flavor: dict, optional

   :returns: True if line is modal group, modal group
   :rtype: (bool, list)


.. py:function:: replacement_function(match)