Merge pull request GaijinEntertainment#2101 from GaijinEntertainment/doc-doc

for loop macro

Author: borisbat

doc/source/reference/tutorials.rst

@@ -152,4 +152,5 @@ Run any tutorial from the project root::
    tutorials/macros/05_tag_function_macro.rst
    tutorials/macros/06_structure_macro.rst
    tutorials/macros/07_block_macro.rst
-   tutorials/macros/08_variant_macro.rst
+   tutorials/macros/08_variant_macro.rst
+   tutorials/macros/09_for_loop_macro.rst

doc/source/reference/tutorials/macros/08_variant_macro.rst

@@ -342,6 +342,8 @@ Key takeaways
 
    Previous tutorial: :ref:`tutorial_macro_block_macro`
 
+   Next tutorial: :ref:`tutorial_macro_for_loop_macro`
+
    Standard library:
    ``daslib/interfaces.das`` (``InterfaceAsIs`` macro),
    ``daslib/ast_boost.das`` (``BetterRttiVisitor``),

doc/source/reference/tutorials/macros/09_for_loop_macro.rst

@@ -0,0 +1,237 @@
+.. _tutorial_macro_for_loop_macro:
+
+.. index::
+   single: Tutorial; Macros; For-Loop Macro
+   single: Tutorial; Macros; for_loop_macro
+   single: Tutorial; Macros; AstForLoopMacro
+   single: Tutorial; Macros; table iteration
+
+====================================================
+ Macro Tutorial 9: For-Loop Macros
+====================================================
+
+Previous tutorials transformed calls, functions, structures, blocks, and
+variants.  For-loop macros operate on **for-loop expressions** — they
+intercept ``for (... in ...)`` at compile time and can rewrite the entire
+loop before type inference finalises.
+
+``[for_loop_macro(name="X")]`` registers a class that extends
+``AstForLoopMacro``.  The compiler calls the macro's single method
+after each for-loop's sources have been type-checked:
+
+``visitExprFor(prog, mod, expr)``
+   Called after visiting the for-loop body, during type inference.
+   Source types are resolved.  Return a replacement ``ExpressionPtr``
+   to transform the loop;  return ``default<ExpressionPtr>`` to skip.
+
+
+Motivation
+==========
+
+daslang tables (``table<K;V>``) are not directly iterable.  The standard
+idiom to iterate a table requires the verbose ``keys()`` and ``values()``
+built-in functions:
+
+.. code-block:: das
+
+   for (k, v in keys(tab), values(tab)) {
+       print("{k} => {v}\n")
+   }
+
+This tutorial builds a for-loop macro that supports a much more natural
+tuple-destructuring syntax:
+
+.. code-block:: das
+
+   for ((k,v) in tab) {       // rewrites to keys/values automatically
+       print("{k} => {v}\n")
+   }
+
+The ``(k,v)`` syntax is **already supported by the parser** — it
+produces a backtick-joined iterator name (``k`v``) and sets a
+tuple-expansion flag.  All the macro needs to do is detect a table
+source, split the name, and rewrite the loop.
+
+.. note::
+
+   Macros cannot be used in the module that defines them.  This tutorial
+   has **two** source files: a *module* file containing the macro
+   definition and a *usage* file that requires the module and exercises it.
+
+
+The macro module
+================
+
+Prerequisites
+-------------
+
+::
+
+  require ast                // AST node types (ExprFor, ExprCall, etc.)
+  require daslib/ast_boost   // AstForLoopMacro base class, [for_loop_macro]
+  require strings            // find, slice — for splitting the iterator name
+
+
+Step 1 — Registration
+---------------------
+
+.. literalinclude:: ../../../../../tutorials/macros/for_loop_macro_mod.das
+   :language: das
+   :lines: 15-18
+
+``[for_loop_macro(name=table_kv)]`` registers ``TableKVForLoop`` so the
+compiler calls ``visitExprFor`` for every for-loop in modules that
+``require`` this one.
+
+
+Step 2 — Detect a table source with tuple expansion
+----------------------------------------------------
+
+Each for-loop's ``ExprFor`` node has several parallel vectors:
+
+``sources``
+   Source expressions (the ``in`` parts).
+``iterators``
+   Iterator variable names.
+``iteratorsAt``
+   Source locations for each iterator.
+``iteratorsAka``
+   Alias names (from ``aka``).
+``iteratorsTags``
+   Tag expressions.
+``iteratorsTupleExpansion``
+   ``uint8`` flag per iterator — nonzero if the parser saw ``(k,v)`` syntax.
+``iteratorVariables``
+   Resolved variables (populated by inference, cleared on rewrite).
+
+The macro scans for a source where the tuple-expansion flag is set
+**and** the source type is a table:
+
+.. literalinclude:: ../../../../../tutorials/macros/for_loop_macro_mod.das
+   :language: das
+   :lines: 23-31
+
+
+Step 3 — Split the backtick-joined name
+----------------------------------------
+
+When the user writes ``(k,v)``,  the parser stores the iterator name as
+``"k`v"`` (joined with a backtick).  The macro splits this into
+``key_name`` and ``val_name``:
+
+.. literalinclude:: ../../../../../tutorials/macros/for_loop_macro_mod.das
+   :language: das
+   :lines: 36-42
+
+
+Step 4 — Clone and rewrite
+---------------------------
+
+The transformation follows the same pattern as the standard library's
+``SoaForLoop`` (in ``daslib/soa.das``):
+
+1. **Clone** the entire ``ExprFor``.
+2. **Erase** the table entry at ``tab_index`` from all parallel vectors.
+3. **Add** two new sources — ``keys(tab)`` and ``values(tab)`` — with
+   the split iterator names.
+4. **Clear** ``iteratorVariables`` so inference rebuilds them on the
+   next pass.
+
+.. literalinclude:: ../../../../../tutorials/macros/for_loop_macro_mod.das
+   :language: das
+   :lines: 43-72
+
+The helper ``make_kv_call`` builds an ``ExprCall`` node for ``keys()``
+or ``values()``:
+
+.. literalinclude:: ../../../../../tutorials/macros/for_loop_macro_mod.das
+   :language: das
+   :lines: 77-80
+
+
+Using the macro
+===============
+
+Section 1 — Verbose (without macro)
+------------------------------------
+
+.. literalinclude:: ../../../../../tutorials/macros/09_for_loop_macro.das
+   :language: das
+   :lines: 16-21
+
+This is the standard idiom: ``keys()`` and ``values()`` return separate
+iterators that advance in lock-step.
+
+
+Section 2 — Tuple destructuring
+---------------------------------
+
+.. literalinclude:: ../../../../../tutorials/macros/09_for_loop_macro.das
+   :language: das
+   :lines: 27-30
+
+Exactly the same output, but the syntax is more natural.  The macro
+rewrites this to the verbose form transparently.
+
+
+Section 3 — Mixed sources
+---------------------------
+
+The macro handles the table source independently; other sources in the
+same loop are preserved:
+
+.. literalinclude:: ../../../../../tutorials/macros/09_for_loop_macro.das
+   :language: das
+   :lines: 37-40
+
+Here ``(k,v)`` iterates over the table while ``idx`` counts from
+``range(100)``.  All three advance in parallel.
+
+
+Running the tutorial
+====================
+
+::
+
+  daslang.exe tutorials/macros/09_for_loop_macro.das
+
+Expected output::
+
+  --- Section 1: table iteration without the macro ---
+    one => 1
+    three => 3
+    two => 2
+
+  --- Section 2: for ((k,v) in tab) with the macro ---
+    one => 1
+    three => 3
+    two => 2
+
+  --- Section 3: mixed sources ---
+    [0] apple => 10
+    [1] banana => 20
+    [2] cherry => 30
+
+(Table iteration order may vary.)
+
+
+Real-world example
+==================
+
+The standard library module ``daslib/soa.das`` uses the same mechanism.
+Its ``SoaForLoop`` macro rewrites ``for (it in soa_struct)`` to iterate
+over the individual arrays of a structure-of-arrays layout — a more
+complex transformation but the same ``AstForLoopMacro`` pattern.
+
+
+.. seealso::
+
+   Full source:
+   :download:`09_for_loop_macro.das <../../../../../tutorials/macros/09_for_loop_macro.das>`,
+   :download:`for_loop_macro_mod.das <../../../../../tutorials/macros/for_loop_macro_mod.das>`
+
+   Previous tutorial: :ref:`tutorial_macro_variant_macro`
+
+   Standard library: ``daslib/soa.das`` (``SoaForLoop`` macro)
+
+   Language reference: :ref:`Macros <macros>` — full macro system documentation

src/ast/ast_infer_type.cpp

@@ -4412,8 +4412,9 @@ namespace das {
                 if (pVar->type && !pVar->type->isTuple()) {
                     error("for loop iterator variable " + pVar->name + " is not a tuple", "", "",
                           expr->at, CompilationError::invalid_iteration_source);
+                } else {
+                    expandTupleName(pVar->name, pVar->at);
                 }
-                expandTupleName(pVar->name, pVar->at);
             }
             ++idx;
         }

tests/interfaces/test_missing_inherited.das

@@ -24,8 +24,3 @@ class Partial {
         return "bar"
     }
 }
-
-[export]
-def main() {
-    pass
-}

tests/interfaces/test_missing_method.das

@@ -17,8 +17,3 @@ class Incomplete {
         pass
     }
 }
-
-[export]
-def main() {
-    pass
-}

tutorials/macros/09_for_loop_macro.das

@@ -0,0 +1,48 @@
+options gen2
+
+// Tutorial 09 — For-loop macro
+//
+// Demonstrates AstForLoopMacro (registered via [for_loop_macro]).
+// The macro module defines a for_loop_macro that enables
+//   for ((k,v) in tab)
+// syntax on tables, rewriting it to
+//   for (k, v in keys(tab), values(tab))
+
+require for_loop_macro_mod
+
+// ---- Section 1: without the macro (the verbose way) -------------------------
+
+def section1() {
+    print("--- Section 1: table iteration without the macro ---\n")
+    var tab <- { "one" => 1, "two" => 2, "three" => 3 }
+    for (k, v in keys(tab), values(tab)) {
+        print("  {k} => {v}\n")
+    }
+}
+
+// ---- Section 2: with the for_loop_macro -------------------------------------
+
+def section2() {
+    print("\n--- Section 2: for ((k,v) in tab) with the macro ---\n")
+    var tab <- { "one" => 1, "two" => 2, "three" => 3 }
+    for ((k, v) in tab) {
+        print("  {k} => {v}\n")
+    }
+}
+
+// ---- Section 3: mixed sources -----------------------------------------------
+
+def section3() {
+    print("\n--- Section 3: mixed sources ---\n")
+    var tab <- { "apple" => 10, "banana" => 20, "cherry" => 30 }
+    for ((k, v), idx in tab, range(100)) {
+        print("  [{idx}] {k} => {v}\n")
+    }
+}
+
+[export]
+def main() {
+    section1()
+    section2()
+    section3()
+}