From: Arran Cudbard-Bell Date: Fri, 16 Aug 2019 02:23:36 +0000 (-0400) Subject: Fixup documentation for regular expressions X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c77cde782bc7a72df739e65b910bede2d50d80d9;p=thirdparty%2Ffreeradius-server.git Fixup documentation for regular expressions --- diff --git a/doc/antora/modules/unlang/pages/regex.adoc b/doc/antora/modules/unlang/pages/regex.adoc index 80f831ebf7e..70f48323393 100644 --- a/doc/antora/modules/unlang/pages/regex.adoc +++ b/doc/antora/modules/unlang/pages/regex.adoc @@ -3,23 +3,24 @@ .Example [source,unlang] ---- -(data =~ /regex/) -(data =~ /regex/i) +( =~ //) +( =~ //[imsux]) -(data !~ /regex/) -(data !~ /regex/i) +( !~ //) +( !~ //[imsux]) ---- +== Matching The regular expression operators perform regular expression matching -on the data. The `data` field can be an attribute reference or data, -as with the other xref:condition/cmp.adoc[comparison] operators. The `/regex/` +on the data. The `` field can be an attribute reference or data, +as with the other xref:condition/cmp.adoc[comparison] operators. The `//` field must be a valid regular expression. The `=~` operator evaluates to `true` when `data` matches the -`/regex/` expression. Otherwise, it evaluates to `false`. +`//`. Otherwise, it evaluates to `false`. The `!~` operator evaluates to `true` when `data` does not match the -`/regex/` expression. Otherwise, it evaluates to `true`. +`//`. 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 @@ -30,8 +31,11 @@ xref:attr.adoc[&Attribute-Name], then the regular expression will behave is if the attribute was printed to a string, and the match was performed on the resulting string. +== 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 @@ -39,21 +43,72 @@ 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]. -* link:http://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended[ +* Functions provided by the local libc implementation, usually +link:http://en.wikipedia.org/wiki/Regular_expression#POSIX_basic_and_extended[ Posix regular expressions]. -The regular expression may be followed by a single `i` character. The -`i` indicates that the regular expression match should be done in a -case-insensitive fashion. +[TIP] +==== +Use the output of `radiusd -Xxv` to determine the regular expression library is in use. + +[source,shell] +---- +... +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, and a warning will be emitted. +==== + +== Flags + +The regular expression `//` 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 may be set per `/pattern/`. + +.Flags and their uses + +[options="header"] +|===== +| Flag Character | Available in | 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 `=~` operator is used, then parentheses in the regular expression will define variables that contain the matching text. -The special variable `%\{0\}` contains a copy of the result of -evaluating the data field. The variables `%\{1\}` and following refer -to the subsequent matched substring in the regular expression. +The special expansion `+%{0}+` expands to the portion of the subject that +matched. The expansions `+%{1}+`..`+%{32}+` expand to the contents of any +capture groups in the pattern. + +When using libpcre[2], named capture groups may also be accessed using the +built-in expansion `+%{regex:}+ + +Return named subcapture value from the last regular expression evaluated. + +Results of named capture groups are available using the `%{regex:}` expansion. They will also be accessible using the numbered expansions +described <<_0_32,above>>. + +Every time a regular expression is evaluated, whether it matches or not, +the named capture group values will be cleared. + +[NOTE] +==== +This expansion is only available if the server is built with libpcre or libpcre2. +Use the output of `radiusd -Xxv` to determine the regular expression library in use. + +[source,shell] +---- +... +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 +---- +==== === +%{nexttime: