= Regular Expressions

.Syntax
====
[source,unlang]
----
(<subject> =~ /<pattern>/)
(<subject> =~ /<pattern>/[imsux])

(<subject> !~ /<pattern>/)
(<subject> !~ /<pattern>/[imsux])
----
====

== Matching
The regular expression operators perform regular expression matching
on the data. The `<subject>` field can be an attribute reference or data,
as with the other xref:unlang/condition/cmp.adoc[comparison] operators.  The `/<pattern>/`
field must be a valid regular expression.

The `=~` operator evaluates to `true` when `data` matches the
`/<pattern>/`.  Otherwise, it evaluates to `false`.

The `!~` operator evaluates to `true` when `data` does not match the
`/<pattern>/`.  Otherwise, it evaluates to `true`.

The regular expression comparison is performed on the _string representation_
of the left side of the comparison.  That is, if the left side is an
xref:type/numb.adoc[integer], the regular expression will behave as if the
value `0` was the literal string `"0"`.  Similarly, if the left side is an
xref:unlang/attr.adoc[&Attribute-Name], then the regular expression will behave
as if the attribute was printed to a string, and the match was performed on the
resulting string.

.Checking if the `User-Name` attribute contains a realm of example.com
====
[source,unlang]
----
if (&User-Name =~ /@example\.com$/) {
    ...
}
----
====

== Dialects

The syntax of the regular expression is defined by the regular
expression library available on the local system.

FreeRADIUS currently supports:

* link:https://www.pcre.org/original/doc/html/[libpcre] and
link:https://www.pcre.org/current/doc/html/[libpcre2] both of which
provide
link:https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions[Perl
Compatible Regular expressions].
* Regex support provided by the local libc implementation, usually
link:http://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended[
Posix regular expressions].

[TIP]
====
Use the output of `radiusd -Xxv` to determine which regular expression library is in use.

....
...
Debug :   regex-pcre               : no
Debug :   regex-pcre2              : yes
Debug :   regex-posix              : no
Debug :   regex-posix-extended     : no
Debug :   regex-binsafe            : yes
...
Debug :   pcre2                    : 10.33 (2019-04-16) - retrieved at build time
....
====

[WARNING]
====
Depending on the regular expression library or libc implementation the server
was built against, the pattern matching function available may not be binary
safe (see `regex-binsafe` in the output of `radiusd -Xxv`).

If a binary safe regex match function is not available, and a match is
attempted against a subject that contains one or more `NUL` ('\0') bytes, the
match will be aborted, any condition that uses the result will evaluate to false,
and a warning will be emitted.
====

== Flags

The regular expression `/<pattern>/` may be followed by one or more flag
characters. Again, which flags are available depends on the regular expression
library the server was built with.  Multiple flags may be specified per
`/pattern/`.

.Flags and their uses

[options="header"]
|=====
| Flag Character | Available with | Effect
| `i`            | All            | Enable case-insensitive matching.
| `m`            | All            | '^' and '$' match newlines within the subject.
| `s`            | libpcre[2]     | '.' matches anything, including newlines.
| `u`            | libpcre[2]     | Treats subjects as UTF8.  Invalid UTF8
                                    sequences will result in the match failing.
 |`x`            | libpcre[2]     | Allows comments in expressions by ignoring
                                    whitespace, and text between '#' and the next
                                    newline character.
|=====

== Subcapture groups

When the `=~` or `!~` operators are used, then parentheses in the regular
expression will sub capture groups, which contain part of the subject string.

The special expansion `%{0}` expands to the portion of the subject that
matched. The expansions +
`%{1}`..`%{32}` expand to the contents of any subcapture groups.

When using libpcre[2], named capture groups may also be accessed using the
built-in expansion +
`%regex(<named capture group>)`.

Please see the xref:xlat/builtin.adoc#_0_32[xlat documentation] for
more information on regular expression matching.

.Extracting the 'user' portion of a realm qualified string
====
[source,unlang]
----
if (&User-Name =~ /^(.*)@example\.com$/) {
    &reply += {
        Reply-Message = "Hello %{1}"
    }
}
----
====

== Dynamic expressions and escaping

If the pattern contains a xref:xlat/index.adoc[dynamic expansion], elements
of the expansion could potentially affect pattern evaluation in unanticipated ways.

To prevent this, the server will, by default, escape any special characters
in the values produced by the dynamic expansion, so that they are treated as
literal characters in the regular expression.

To allow non-literals in dynamic elements of regular expressions, wrap any literal
values or expansions in `%regex.safe(...)`.

.Using regex.safe to prevent escaping
====
[source,unlang]
----
local pattern
switch (realm) {
    case example.com {
        pattern = %regex.safe('.*\.example\.com')
    }
    case test.com {
        # '.' does not need to be escaped
        pattern = 'test.com'
    }
}

if (&Stripped-User-Name =~ /^%{pattern}$/) {
    ...
}
----
====

== Pre-Compiled vs Runtime Compiled

When the server starts any regular expressions comparisons it finds will be
pre-compiled, and if support is available, JIT'd (converted to machine code)
to ensure fast execution.

If a pattern contains a xref:xlat/index.adoc[dynamic expansion], the pattern
cannot be compiled on startup, and will be compiled at runtime each time the
expression is evaluated. The server will also turn off JITing for runtime
compiled expressions, as the overhead is greater than the time that would be
saved during evaluation.

.A runtime compiled regular expression
====
[source,unlang]
----
if (&User-Name =~ /^@%{Tmp-String-0}$/) {
    ...
}
----
====

To ensure optimal performance you should limit the number of patterns
containing xref:xlat/index.adoc[dynamic expansions], and if using PCRE, combine
multiple expressions operating on the same subject into a single expression
using the PCRE alternation '|' operator.

.Using multiple dynamic expansions and the PCRE alternation operator
====
[source,unlang]
----
if (&User-Name =~ /^@(%{Tmp-String-0}|%{Tmp-String-1})$/) {
    ...
}
----
====


// Licenced under CC-by-NC 4.0.
// Copyright (C) 2021 Network RADIUS SAS.
// Copyright (C) 2019 Arran Cudbard-Bell <a.cudbardb@freeradius.org>
// This documentation was developed by Network RADIUS SAS.
