step.motion.path.compiler
=========================

.. py:module:: step.motion.path.compiler

.. autoapi-nested-parse::

   PathCompiler — turns a list of Steps into a CompiledPlan.

   The compiler is a thin orchestrator: it lowers the input Step tree into the
   IR via the lowering pass, then runs each subsequent CompilerPass in sequence
   on the resulting node list.  The result is a ``CompiledPlan`` that the
   ``PathExecutor`` knows how to run.



Classes
-------

.. autoapisummary::

   step.motion.path.compiler.CompilerPass
   step.motion.path.compiler.CompiledPlan
   step.motion.path.compiler.PathCompiler


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

.. py:class:: CompilerPass

   Bases: :py:obj:`Protocol`


   Pure transform on the path IR.

   A pass takes a node list and returns a (possibly different) node list.
   Passes must preserve the "deferred placeholder" (``None``) entries so
   the executor can resolve them at runtime.


   .. py:attribute:: name
      :type:  str


   .. py:method:: run(nodes: list[step.motion.path.ir.PathNode | None]) -> list[step.motion.path.ir.PathNode | None]


.. py:class:: CompiledPlan

   Result of compiling a Step tree.

   ``nodes``        — the path IR after all passes ran.  Spline mode lowers
                      to a single ``Segment(kind="spline")`` node here, so the
                      executor walks it through the unified loop like any
                      other opaque segment.
   ``deferred``     — ``(index, Defer)`` pairs for runtime resolution.
   ``passes_applied`` — names of passes that ran, for diagnostics.


   .. py:attribute:: nodes
      :type:  list[step.motion.path.ir.PathNode | None]


   .. py:attribute:: deferred
      :type:  list[tuple[int, step.logic.defer.Defer]]


   .. py:attribute:: passes_applied
      :type:  list[str]
      :value: []



.. py:class:: PathCompiler(passes: list[CompilerPass] | None = None)

   Orchestrates the compiler pipeline.

   Lowering is always run first (it produces the IR from the Step tree).
   The remaining passes are applied in the order given.

   .. rubric:: Example

   >>> from raccoon.step.motion.path.passes import MergePass, CornerCutPass
   >>> compiler = PathCompiler([MergePass(), CornerCutPass(0.05)])
   >>> plan = compiler.compile([drive(50), turn(90), drive(30)])


   .. py:method:: compile(steps: list) -> CompiledPlan

      Lower ``steps`` to IR and run all configured passes.