From: Alan T. DeKok <aland@freeradius.org>
Date: Sat, 17 May 2025 12:16:05 +0000 (-0400)
Subject: document common v3 pattern of ":=" followed by "+="
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e5b301e8eece1c022aec86b7ef1527619b0df4a0;p=thirdparty%2Ffreeradius-server.git

document common v3 pattern of ":=" followed by "+="
---

diff --git a/doc/antora/modules/reference/pages/unlang/update.adoc b/doc/antora/modules/reference/pages/unlang/update.adoc
index de7062b4105..1d63581fe2c 100644
--- a/doc/antora/modules/reference/pages/unlang/update.adoc
+++ b/doc/antora/modules/reference/pages/unlang/update.adoc
@@ -30,14 +30,49 @@ There are a larger number of operators using for both the old `update`
 section and the xref:unlang/edit.adoc[edit] syntax.  We explain in
 detail how the configuration can be converted from one form to another.
 
+=== Over-writing attributes in a list: :=
+
+The following example over-writes the values for two attributes in the
+`reply` list.
+
+[source,unlang]
+----
+update reply {
+	User-Name := "foo"
+	Filter-Id := "bar"
+}
+----
+
+The simplest conversion here is to keep the `:=` operator, and to just
+assign the attributes in place, with a list qualifier.
+
+[source,unlang]
+----
+reply.User-Name := "foo"
+reply.Filter-Id := "bar"
+----
+
+Note that the following assignment is _not_ correct, as it will
+overwrite the _entire_ request list.  Once the overwrite has been
+done, the `reply` list will contain only the two attributes being
+assigned to it.
+
+[source,unlang]
+----
+reply := {
+	User-Name = "foo"
+	Filter-Id = "bar"
+}
+----
+
 === Appending to a list: +=
 
 The following example creates four attributes, and appends them to the
-`request` list.
+`reply` list.
 
 [source,unlang]
 ----
-update request {
+update reply {
 	User-Name += "foo"
 	Filter-Id += "bar"
 	NAS-IP-Address += 127.0.0.1
@@ -57,7 +92,7 @@ request += {
 }
 ----
 
-This configuration can be interpreted as "edit the `request` list,
+This configuration can be interpreted as "edit the `reply` list,
 but appending (`+=`) another list to it.  The list being appended
 contains four attributes".
 
@@ -65,48 +100,39 @@ Note that the operators on the right-hand side list are all `=`.  The
 `=` operator is used here because we are simply _creating_ the
 right-hand side list, not _modifying_ it.
 
-=== Over-writing attributes in a list: :=
+=== Adding many of the same Attribute
 
-The following example over-writes the values for two attributes in the
-`request` list.
+A common pattern is to use `:=` and `+=` in order to remove all
+previous values of an attribute, and then to add new values:
 
 [source,unlang]
 ----
-update request {
-	User-Name := "foo"
+update reply {
 	Filter-Id := "bar"
+	Filter-Id += "foo"
+	Filter-Id += "baz"
 }
 ----
 
-The simplest conversion here is to keep the `:=` operator, and to just
-assign the attributes in place, with a list qualifier.
+The server now supports setting multiple values to a leaf attribute,
+via a list assignment.  The above `update` section can then be
+converted to a one-line edit statement:
 
 [source,unlang]
 ----
-request.User-Name := "foo"
-request.Filter-Id := "bar"
+reply.Filter-Id := { "bar", "boo", "baz" }
 ----
 
-Note that the following conversion is _not_ correct, as it will
-overwrite the _entire_ request list.  Once the overwrite has been
-done, the `request` list will contain only the two attributes being
-assigned to it.
+This functionality makes it much easier to write complex assignments.
 
-[source,unlang]
-----
-request := {
-	User-Name = "foo"
-	Filter-Id = "bar"
-}
-----
 === Conditionally Over-writing attributes in a list: =
 
 The following example conditionally over-writes the values for two attributes in the
-`request` list.
+`reply` list.
 
 [source,unlang]
 ----
-update request {
+update reply {
 	User-Name = "foo"
 	Filter-Id = "bar"
 }
@@ -117,17 +143,17 @@ assign the attributes in place, with a list qualifier.
 
 [source,unlang]
 ----
-request.User-Name = "foo"
-request.Filter-Id = "bar"
+reply.User-Name = "foo"
+reply.Filter-Id = "bar"
 ----
 
 === Removing Attributes from a list: !*
 
-The following example removes all `User-Name` attributes from the `request` list.
+The following example removes all `User-Name` attributes from the `reply` list.
 
 [source,unlang]
 ----
-update request {
+update reply {
 	User-Name !* ANY
 }
 ----
@@ -136,7 +162,7 @@ The conversion is to use the `-=` operator:
 
 [source,unlang]
 ----
-request -= User-Name
+reply -= User-Name
 ----
 
 == More Complex Conversions
@@ -176,5 +202,5 @@ allowed the separation of list assignments from value modifications,
 which meant that xref:unlang/expression.adoc[expressions] became
 became simpler.
 
-// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Copyright (C) 2025 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // This documentation was developed by Network RADIUS SAS.