From: Alan T. DeKok <aland@freeradius.org>
Date: Tue, 22 Nov 2022 14:00:54 +0000 (-0500)
Subject: document request.[x] syntax
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a28af5498406a34c0b733fcccea8c3c18fd61c3c;p=thirdparty%2Ffreeradius-server.git

document request.[x] syntax
---

diff --git a/doc/antora/modules/reference/pages/unlang/attr.adoc b/doc/antora/modules/reference/pages/unlang/attr.adoc
index 821a375ece1..a4ce8c15747 100644
--- a/doc/antora/modules/reference/pages/unlang/attr.adoc
+++ b/doc/antora/modules/reference/pages/unlang/attr.adoc
@@ -58,6 +58,24 @@ etc.
 &reply.NAS-IP-Address[2]
 ----
 
+=== Array References in lists
+
+It is sometimes useful to refer to children of a list, without
+addressing the children by name.  In that case, the name of the child
+attribute can be omitted, as follow:
+
+.Examples
+[source,unlang]
+----
+&request.[0]
+----
+
+i.e. "the first child of the `request` list.
+
+This syntax is most useful in xref:xlat/attribute.adoc[xlat attribute references].
+
+Note that the old syntax of `&request[...]` is disallowed.
+
 == Parent / child references
 
 .Syntax
@@ -105,5 +123,5 @@ parse the configuration files correctly in all cases.
 Adding the leading `&` character means that attribute references are
 now easily distinguishable from literal strings.
 
-// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Copyright (C) 2022 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.
diff --git a/doc/antora/modules/reference/pages/xlat/attribute.adoc b/doc/antora/modules/reference/pages/xlat/attribute.adoc
index 7c75e0e89c9..30ce0df319f 100644
--- a/doc/antora/modules/reference/pages/xlat/attribute.adoc
+++ b/doc/antora/modules/reference/pages/xlat/attribute.adoc
@@ -37,6 +37,7 @@ Examples of using references inside of a string:
 == Additional Variations
 
 `%{Attribute-Name[#]}`::
+
 Returns an integer containing the number of named attributes
 
 `%{Attribute-Name[0]}`::
@@ -50,5 +51,29 @@ the first attributes, `[1]` refers to the second attribute, etc.
 Returns a comma-separated string containing all values for the named
 attributes.
 
-// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+== Lists and Grouping attributes
+
+There is similar syntax for referencing children of a list, without
+addressing the children by name.
+
+`%{request.[#]}`::
+Returns an integer containing the number of attributes contained in the `request` list.  Any list name can be used.
+
+
+`%{request.[0]}`::
+
+Returns the value of the first attribute in the `request` list.
+
+`%{request.[*]}`::
+
+Returns a comma-separated string containing all values of attributes in the `request` list.
+
+See also xref:unlang/attr.adoc[unlang attribute references].
+
+Note that the old syntax of `%{request[*]}` will instead refer to
+array entries of the `request` list.  This is a change from previous
+versions of the server.  When upgrading, you should just add a `.`
+between the list name and the array reference `[`.
+
+// Copyright (C) 2022 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.