= The foreach Statement

.Syntax
[source,unlang]
----
foreach [<key-type> <key-name>,] [<value-type>] <value-name> (<reference>) {
    [ statements ]
}
----

The `foreach` statement loops over a set of attributes as given by
`<attribute-reference>`.  The loop can be exited early by using the
xref:unlang/break.adoc[break] keyword.

There is no limit to how many `foreach` statements can be nested.

<key-type>::

In conjunction with `<key-name>`, an optional data type for the key or index variable.  The data type should be numeric (e.g. `uint32`) for a `<reference>` which is a dynamic expansion.  The data type should be `string` for a `<reference>` which is an attribute reference.

<key-name>::

The name of the local variable which is used as the name of key when iterating over the attributes.

For numerical data types, the key value starts off at zero (0), and increases by one every round through the loop.  For `string` data types the key value is the full path to the current attribute.

The `<key-type>` and `<key-name>` are optional, and can be omitted.

<value-type>::

An optional data type for the `<value-name>` local variable.  When looping over attributes, the data type can be omitted.  The data type of the local variable is then taken from the attribute reference.

<value-name>::

The name of the local variable which is used as the name of value when iterating over the attributes.

The local variable is created automatically when the `foreach` loop is entered, and is deleted automatically when the `foreach` loop exits.

The `<value-name>` can be modified during the course of the `foreach` loop.  Modifications to the variable are copied back to the referenced attribute when the loop is done.  See below for an example.

The only limitation on the `<value-name>` is that it must be unique.

<reference>::

An xref:unlang/attr.adoc[attribute reference] which will will be looped
over.  The reference can be to one attribute, to an array, a child, or
be a subset of attributes.

Alternatively, the `<reference>` can be a xref:reference:xlat/index.adoc[dynamic expansion function],
such as `%sql("SELECT ...")`.  When the reference is a dynamic
expansion function, a `<value-type>` must be specified.

== Modifying Loop variables

When the `<reference>` is an attribute, the attribute being looped
over can sometimes be modified.  When the `<reference>` is a dynamic
expansion, the results cannot be modified, and are discarded when the
`foreach` loop is finished.  If it is necessary to save the results,
they should be placed into another attribute.

An attribute which is a "leaf" data type (e.g. `uint32`, and not
`tlv`) will be automatically copied back to the original attribute at
the end of each iteration of the `foreach` loop.  That is, the
original attribute will still exist, and will be unmodified, during
the execution of the loop.

.Example of modifying values
[source,unlang]
----
&Tmp-Integer-0 := { 1, 3, 5, 11 }

foreach self (&Tmp-Integer-0) {
	&self += 19
}
----

Once the loop has finished , the `&Tmp-Integer-0` attribute will have the following set of values.

[source,unlang]
----
&Tmp-Integer-0 := { 20, 22, 24, 30 }
----

.Pseudocode for variable modification
----
loop over each i in attribute[0..n]
    copy attribute[i] to the key variable, or cast the attribute to the destination type

    run loop body

    if data type of attribute matches the data type of the key
        copy the key variable back to attribute[i]
----

=== Keys

Using a key variable allows the loop to determine exactly which attribute is being modified.  Or for dynamic expansions, which of `0..n` values are being examined.

For attributes, the `<key-type>` must be `string`.  For dynamic expansions, it must be a numerical type such as `uint32`.

.Key variable with attribute
[source,unlang]
----
string total
&Tmp-Integer-0 := { 1, 3, 5, 11 }

foreach string ref, uint32 self (Tmp-Integer-0) {
	total += ref
	total += " = "
	total += (string) self
	ttoal += ", "
}
----

When the loop is finished, the `total` variable will have the following value:

----
"Tmp-Integer-0[0] = 1, "Tmp-Integer-0[1] = 3, "Tmp-Integer-0[2] = 5, "Tmp-Integer-0[3] = 11, "
----

A dynamic expansion can use a keyed index.  If the `SELECT` statement below returns a list of `"a", "b", "c", "d"`. then we have the following example:

.Key variable with expansion
[source,unlang]
----
string total

foreach uint32 index, string data (%sql("SELECT ...") {
	total += (string) index
	total += ":"
	total += data
	ttoal += ", "
}
----

When the loop is finished, the `total` variable will have the following value:

----
"0:a, 1:b, 2:c, 3:d, "
----

=== Structural Data Types

It is possible to loop over the children of a structural data type, as given in the example below.  Since the loop is over the child (i.e. leaf) attributes, the values are copied back.

In this example, we have to explicitly give a data type `string`.  The data type is needed because there may be multiple children of the `TLV-Thing` attribute, and the children may not all have the same data type.

.Example of Looping over children of a structural type.
[source,unlang]
----
foreach string child (&TLV-Thing.[*]) {
	&out += &child
	&out += " "
}
----


When using `foreach` to loop over multiple structural data types, the values can be
examined, but cannot be changed.  This is a limitation of the current interpreter, and may be changed in the future.

.Example of Looping over children of a structural type.
[source,unlang]
----
foreach thing (&Tmp-TLV-0[*]) {
	&out += &thing.c
	&out += " "
}
----

This example can read the child attribute `c`, but cannot modify it.


// Copyright (C) 2024 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
