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 821a375ece173eb8c912c147c87f0864482455cc..a4ce8c15747e878c0eef336aa9b98e129d587e20 100644 (file)
--- 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 7c75e0e89c9031066767653c565beda7ad12ad29..30ce0df319f5f1d205ecf9241cd17bbdcf4a4c1c 100644 (file)
--- 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.