= &Attribute References

Attributes may be referenced via the following syntax:

.Syntax
[source,unlang]
----
&Attribute-Name
&Attribute-Name:TAG
&Attribute-Name[NUM]
&<list>:Attribute-Name
&<list>:Attribute-Name:TAG[NUM]
----

The `&Attribute-Name` operator returns a reference to the named
attribute.

When used as an existence check in a condition, the condition
evaluates to `true` if the attribute exists.  Otherwise, the condition
evaluates to `false`.

When used elsewhere, such as in xref:switch.adoc[switch], it returns
the value of the named attribute.

.Examples
[source,unlang]
----
&User-Name
&NAS-IP-Address
----

== Lists

The attribute reference can also be qualified with a
xref:list.adoc[list] reference.  When no list is given, the server
looks in the input packet list for the named attribute.

.Examples

[source,unlang]
----
&request:User-Name
&reply:NAS-IP-Address
----

== Array References

Finding a particular attribute from multiple instances can be done via
an array reference.

.Syntax
[source,unlang]
----
&Attribute-Name[<integer>]
----

When an attribute appears multiple times in a list, this syntax allows
you to address the attributes as if they were array entries.  The
`<integer>` value defines which attribute to address.  The `[0]` value
refers to the first attributes, `[1]` refers to the second attribute,
etc.

.Examples
[source,unlang]
----
&EAP-Message[1]
&reply:NAS-IP-Address[2]
----

== Other Array indexes

The array syntax can be used for a few special cases, too.

.Syntax
[source,unlang]
----
&Attribute-Name[#]
&Attribute-Name[*]
&Attribute-Name[n]
----

These extra fields have the following definitions:

`#`::
Returns an integer which is the number of instances of this attribute.

`*`::
Returns all of the instances of the given attribute.  This syntax can only be used in a xref:xlat/index.adoc[string expansion].  It will return all of the values of the attribute, separated by commas.

`n`::
Returns the last instance of the given attribute.

== Removing ambuguity from the configuration files

In most cases, the server uses the `&` character to distinguish
attribute names from other strings.

Without the `&`, it is more difficult to parse the configuration file
clearly. You could interpret a string as `hello-there`
either as a literal string "hello-there", or as a reference to an
attribute named `hello-there`.  

Adding the leading `&` character means that attribute references are
now easily distinguishable from literal strings.  The use of the leading 
`&` character is highly recommended.


// Copyright (C) 2025 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
// Development of this documentation was sponsored by Network RADIUS SAS.
