Reorganize the for tag docs

doc/tags/for.rst

@@ -50,92 +50,6 @@ The ``..`` operator can take any expression at both sides:
     If you need a step different from 1, you can use the ``range`` function
     instead.
 
-The ``loop`` variable
----------------------
-
-Inside of a ``for`` loop block you can access some special variables:
-
-===================== ========================================================================
-Variable              Description
-===================== ========================================================================
-``loop.index``        The current iteration of the loop. (1 indexed)
-``loop.index0``       The current iteration of the loop. (0 indexed)
-``loop.revindex``     The number of iterations from the end of the loop (1 indexed)
-``loop.revindex0``    The number of iterations from the end of the loop (0 indexed)
-``loop.first``        True if first iteration
-``loop.last``         True if last iteration
-``loop.length``       The number of items in the sequence
-``loop.parent``       The parent context
-``loop.cycle``        Cycle over a sequence of values
-``loop.changed``      True if previously called with a different value or if not called yet
-``loop.previous``     The value from the previous iteration (``null`` for the first iteration)
-``loop.next``         The value from the next iteration (``null`` for the last iteration)
-===================== ========================================================================
-
-.. code-block:: twig
-
-    {% for user in users %}
-        {{ loop.index }} - {{ user.username }}
-    {% endfor %}
-
-Use ``loop.cycle`` to cycle among a list of values:
-
-.. code-block:: html+twig
-
-    {% for row in rows %}
-        <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
-    {% endfor %}
-
-Use ``loop.previous`` and ``loop.next`` to access the previous or next values:
-
-.. code-block:: twig
-
-    {% for value in values %}
-        {% if not loop.first and value > loop.previous %}
-            The value just increased!
-        {% endif %}
-        {{ value }}
-        {% if not loop.last and loop.next > value %}
-            The value will increase even more!
-        {% endif %}
-    {% endfor %}
-
-``loop.previous`` is ``null`` when called at the first item, and ``loop.next``
-is ``null`` when called at the last item.
-
-Use ``loop.changed`` to check if the value has changed since the last call:
-
-.. code-block:: html+twig
-
-    {% for entry in entries %}
-        {% if loop.changed(entry.category) %}
-            <h2>{{ entry.category }}</h2>
-        {% endif %}
-        <p>{{ entry.message }}</p>
-    {% endfor %}
-
-.. note::
-
-    When the underlying PHP iterator is not countable, the ``loop.length``,
-    ``loop.revindex``, and ``loop.revindex0`` variables are not available and a
-    ``RuntimeException`` is thrown if you try to use them.
-
-The ``else`` Clause
--------------------
-
-If no iteration took place because the sequence was empty, you can render a
-replacement block by using ``else``:
-
-.. code-block:: html+twig
-
-    <ul>
-        {% for user in users %}
-            <li>{{ user.username|e }}</li>
-        {% else %}
-            <li><em>no user found</em></li>
-        {% endfor %}
-    </ul>
-
 Iterating over Keys
 -------------------
 
@@ -179,3 +93,106 @@ the :doc:`slice <../filters/slice>` filter:
             <li>{{ user.username|e }}</li>
         {% endfor %}
     </ul>
+
+The ``else`` Clause
+-------------------
+
+If no iteration took place because the sequence was empty, you can render a
+replacement block by using ``else``:
+
+.. code-block:: html+twig
+
+    <ul>
+        {% for user in users %}
+            <li>{{ user.username|e }}</li>
+        {% else %}
+            <li><em>no user found</em></li>
+        {% endfor %}
+    </ul>
+
+The ``loop`` Object
+-------------------
+
+Inside of a ``for`` loop block, a ``loop`` object exposes some information
+about the current loop iteration.
+
+``loop`` Variables
+~~~~~~~~~~~~~~~~~~
+
+===================== ========================================================================
+Variable              Description
+===================== ========================================================================
+``loop.index``        The current iteration of the loop (1 indexed)
+``loop.index0``       The current iteration of the loop (0 indexed)
+``loop.revindex``*    The number of iterations from the end of the loop (1 indexed)
+``loop.revindex0``*   The number of iterations from the end of the loop (0 indexed)
+``loop.first``        True if first iteration
+``loop.last``         True if last iteration
+``loop.length``*      The number of items in the sequence
+``loop.parent``       The parent context
+``loop.previous``     The value from the previous iteration (``null`` for the first iteration)
+``loop.next``         The value from the next iteration (``null`` for the last iteration)
+===================== ========================================================================
+
+.. note::
+
+    When the underlying PHP iterator is not countable, the ``loop.length``,
+    ``loop.revindex``, and ``loop.revindex0`` variables are not available and a
+    ``RuntimeException`` is thrown if you try to use them.
+
+Here is an example on how to use the ``index`` variable:
+
+.. code-block:: twig
+
+    {% for user in users %}
+        {{ loop.index }} - {{ user.username }}
+    {% endfor %}
+
+Use ``loop.previous`` and ``loop.next`` to access the previous or next values:
+
+.. code-block:: twig
+
+    {% for value in values %}
+        {% if not loop.first and value > loop.previous %}
+            The value just increased!
+        {% endif %}
+        {{ value }}
+        {% if not loop.last and loop.next > value %}
+            The value will increase even more!
+        {% endif %}
+    {% endfor %}
+
+``loop.previous`` is ``null`` when called at the first item, and ``loop.next``
+is ``null`` when called at the last item.
+
+``loop`` Functions
+~~~~~~~~~~~~~~~~~~
+
+The ``loop`` object also exposes some functions:
+
+===================== ========================================================================
+Function              Description
+===================== ========================================================================
+``loop.cycle()``      Cycle over a sequence of values
+``loop.changed()``    True if previously called with a different value or if not called yet
+``loop()``            Allows to iterate over a nested sequence/mapping
+===================== ========================================================================
+
+Use ``loop.cycle()`` to cycle among a list of values:
+
+.. code-block:: html+twig
+
+    {% for row in rows %}
+        <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
+    {% endfor %}
+
+Use ``loop.changed()`` to check if the value has changed since the last call:
+
+.. code-block:: html+twig
+
+    {% for entry in entries %}
+        {% if loop.changed(entry.category) %}
+            <h2>{{ entry.category }}</h2>
+        {% endif %}
+        <p>{{ entry.message }}</p>
+    {% endfor %}