========
Examples
========

SVG-to-Turtle compiler
======================

This example reads a small subset of SVG and compiles it into a Python
module that reproduces the drawing with the standard-library
:mod:`turtle` module.  It demonstrates several fluent-codegen features:

* Building a :class:`~fluent_codegen.codegen.Module` with multiple
  functions.
* Using the :doc:`E-objects system <./e-objects>` (``enames``, ``.e``) for natural-looking
  math and method calls.
* Automatic **name deduplication** — the same local name (``pos``,
  ``heading``) is used for each ``<use>`` element, and the scope
  manager appends suffixes automatically.

Supported SVG elements:

* ``<line x1=… y1=… x2=… y2=…>`` — a straight line segment.
* ``<defs>`` containing ``<line>`` elements with ``id`` attributes —
  compiled into helper functions.
* ``<use href="#id" x="..." y="...">`` — compiled into
  code that calls the helper.

The compiler script
-------------------

Points to note:

- Variables of type ``E`` from the :doc:`E-objects system <./e-objects>`
  have a suffix ``_e`` as a convention.
- Note the use of E-objects in ``_emit_line``, so that the code written mirrors
  the output code almost exactly, but without it being a string or subject to
  the problems of string-based generation.


.. literalinclude:: examples/svg_to_turtle/svg_to_turtle.py
   :language: python
   :caption: ``docs/examples/svg_to_turtle/svg_to_turtle.py``


Sample input
------------

A simple house shape built from ``<line>`` elements and ``<use>``
references to reusable beams/walls defined in ``<defs>``:

.. image:: examples/svg_to_turtle/house.svg
   :align: center


.. literalinclude:: examples/svg_to_turtle/house.svg
   :language: xml
   :caption: ``house.svg``


Generated output
----------------

Running ``python svg_to_turtle.py house.svg`` produces:

.. literalinclude:: examples/svg_to_turtle/house.py
   :language: python
   :caption: ``house.py`` (generated)

Key points to note in the generated code:

* ``_draw_beam()`` and ``_draw_wall()`` are helper functions compiled from the ``<defs>``
  element, with names based on the element names.
* Each ``<use>`` saves the turtle position, calls the
  helper, and restores.
* The local variables ``pos``, ``heading`` are auto-suffixed to
  ``pos_2``, ``heading_2`` for the second ``<use>``.