From: Alan T. DeKok Date: Tue, 12 Dec 2023 13:34:58 +0000 (-0500) Subject: split out string functions into their own files X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=92140dc87c40424842e87c1f77b0ad11743874c6;p=thirdparty%2Ffreeradius-server.git split out string functions into their own files --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index 3ae10bcd91a..0291272a1f8 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -72,6 +72,15 @@ *** xref:xlat/log.adoc[Logging Functions] *** xref:xlat/protocol.adoc[Protocol Encoding and Decoding] *** xref:xlat/string.adoc[String Handling] +**** xref:xlat/concat.adoc[Concatenation] +**** xref:xlat/explode.adoc[Split strings] +**** xref:xlat/length.adoc[Length] +**** xref:xlat/lpad.adoc[Left pad] +**** xref:xlat/pairs.adoc[Print attributes] +**** xref:xlat/rpad.adoc[Right pad] +**** xref:xlat/randstr.adoc[Random strings] +**** xref:xlat/tolower.adoc[Conver to lowercase] +**** xref:xlat/toupper.adoc[Convert to uppercase] *** xref:xlat/builtin.adoc[Built-in Expansions] *** xref:xlat/character.adoc[Single Letter Expansions] *** xref:xlat/attribute.adoc[Attribute References] diff --git a/doc/antora/modules/reference/pages/xlat/concat.adoc b/doc/antora/modules/reference/pages/xlat/concat.adoc new file mode 100644 index 00000000000..40a87bc1b37 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/concat.adoc @@ -0,0 +1,46 @@ += %concat(<&ref:[idx]>, ) + +Used to join two or more attributes, separated by an optional delimiter. + +This expansion is the inverse of xref:xlat/explode.adoc[explode]. + +.Return: _string_ + +In most cases, `%concat(...)` is only useful inside of a dynamically +expanded string. If you need to concatenate strings together in a policy, just use `+`. + +.Example + +[source,unlang] +---- +&control += { + &Tmp-String-0 = "aaa" + &Tmp-String-0 = "bb" + &Tmp-String-0 = "c" +} + +&reply += { + &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ', ')" + &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ',')" +} +---- + +.Output + +``` +aaa, bb, c +aaa,bb,c +``` + +.Using "+" +[source,unlang] +---- +string foo + +&foo += { "a", "c", "c", "d" } # abcd + +&foo += &control.Tmp-String-0[*] +---- + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/dict.adoc b/doc/antora/modules/reference/pages/xlat/dict.adoc new file mode 100644 index 00000000000..43d487bd227 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/dict.adoc @@ -0,0 +1,200 @@ += Dictionary Lookups + +The following functions perform lookups based on dictionary names and numbers. + +The functions are defined in the `dict` module. It must be listed in +the `mods-enabled/` directory in order for the expansions to work. + +== %concat(<&ref:[idx]>, ) + +Used to join two or more attributes, separated by an optional delimiter. + +.Return: _string_ + +In most cases, `%concat(...)` is only useful inside of a dynamically +expanded string. If you need to concatenate strings together in a policy, just use `+`. + +.Example + +[source,unlang] +---- +&control += { + &Tmp-String-0 = "aaa" + &Tmp-String-0 = "bb" + &Tmp-String-0 = "c" +} + +&reply += { + &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ', ')" + &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ',')" +} +---- + +.Output + +``` +aaa, bb, c +aaa,bb,c +``` + +.Using "+" +[source,unlang] +---- +string foo + +&foo += { "a", "c", "c", "d" } # abcd + +&foo += &control.Tmp-String-0[*] +---- + +== %explode(<&ref>, ) + +Split an string into multiple new strings based on a delimiter. + +This expansion is the opposite of `%concat( ... )`. + +.Return: _the number exploded list of strings_. + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "bob.toba@domain.com" + +&control.Tmp-String-1 := "%explode(&control.Tmp-String-0, '@')" + +&reply.Reply-Message := "Welcome %{control.Tmp-String-1[0]}" +---- + +.Output + +``` +Welcome bob.toba +``` + +== %lpad(, , ) + +Left-pad a string. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "123" + +&reply.Reply-Message := "Maximum should be %lpad(%{control.Tmp-String-0}, 11, '0')" +---- + +.Output + +``` +Maximum should be 00000000123 +``` + +== %rpad(, , ) + +Right-pad a string. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "123" + +&reply.Reply-Message := "Maximum should be %rpad(%{control.Tmp-String-0}, 11, '0')" +---- + +.Output + +``` +Maximum should be 12300000000 +``` + +== %pairs(.[*]) + +Serialize attributes as comma-delimited string. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := { "This is a string", "This is another one" } +&reply.Reply-Message := "Serialize output: %pairs(&control.[*])" +---- + +.Output + +``` +Serialize output: Tmp-String-0 = "\"This is a string\", Tmp-String-0 = \"This is another one\"" +``` + +== %randstr( ...) + +Get random string built from character classes. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&reply.Reply-Message := "The random string output is %randstr(aaaaaaaa}" +---- + +.Output + +``` +The random string output is 4Uq0gPyG +``` + +== %tolower( ... ) + +Dynamically expands the string and returns the lowercase version of +it. This definition is only available in version 2.1.10 and later. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "CAIPIRINHA" +&reply.Reply-Message := "tolower of %{control.Tmp-String-0} is %tolower(%{control.Tmp-String-0})" +---- + +.Output + +``` +tolower of CAIPIRINHA is caipirinha +``` + +== %toupper( ... ) + +Dynamically expands the string and returns the uppercase version of +it. This definition is only available in version 2.1.10 and later. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "caipirinha" +&reply.Reply-Message := "toupper of %{control.Tmp-String-0} is " + %toupper(%{control.Tmp-String-0}) +---- + +.Output + +``` +toupper of caipirinha is CAIPIRINHA +``` + + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/explode.adoc b/doc/antora/modules/reference/pages/xlat/explode.adoc new file mode 100644 index 00000000000..b80ffd550f4 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/explode.adoc @@ -0,0 +1,27 @@ += %explode(<&ref>, ) + +Split an string into multiple new strings based on a delimiter. + +This expansion is the inverse of xref:xlat/concat.adoc[concat]. + +.Return: _the list of strings_. + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "bob.toba@domain.com" + +&control.Tmp-String-1 := "%explode(&control.Tmp-String-0, '@')" + +&reply.Reply-Message := "Welcome %{control.Tmp-String-1[0]}" +---- + +.Output + +``` +Welcome bob.toba +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/lpad.adoc b/doc/antora/modules/reference/pages/xlat/lpad.adoc new file mode 100644 index 00000000000..e793fa6aa3d --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/lpad.adoc @@ -0,0 +1,23 @@ += %lpad(, , ) + +Left-pad a string. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "123" + +&reply.Reply-Message := "Maximum should be %lpad(%{control.Tmp-String-0}, 11, '0')" +---- + +.Output + +``` +Maximum should be 00000000123 +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/pairs.adoc b/doc/antora/modules/reference/pages/xlat/pairs.adoc new file mode 100644 index 00000000000..72c7df63783 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/pairs.adoc @@ -0,0 +1,24 @@ += %pairs(.[*]) + +Serialize a list of attributes as comma-delimited string. + +.Return: _string_ + +Note that there is no "convert string to pairs" function. Instead, you can simply assign the string to a structural attribute (`group`, `tlv`, etc.) and the string will be parsed as pairs. + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := { "This is a string", "This is another one" } +&reply.Reply-Message := "Serialize output: %pairs(&control.[*])" +---- + +.Output + +``` +Serialize output: Tmp-String-0 = "\"This is a string\", Tmp-String-0 = \"This is another one\"" +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/randstr.adoc b/doc/antora/modules/reference/pages/xlat/randstr.adoc new file mode 100644 index 00000000000..3a841ffdd00 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/randstr.adoc @@ -0,0 +1,45 @@ += %randstr( ) + +Get random string built from input character classes. + +.Return: _string_ + +Build strings of random chars, useful for generating tokens and passcodes +Format similar to the Perl module `String::Random`. + +Format characters may include the following, and may be +preceeded by an integer repetition count: + +.Character Classes +[options="header"] +[cols="30%,70%"] +|===== +| Character | Description +| c | lowercase letters `[a-z]` +| C | uppercase letters `[A-Z]` +| n | numbers `[0-9]` +| a | alphanumeric +| ! | punctuation `!"#$%&'()*+,-./:;<=>?@[\\]^_{\|}~`` +| . | alphanumeric + punctuation +| s | alphanumeric + `.` and `/` +| o | characters suitable for OTP (visually similar characters removed) +| b | binary data +|===== + +There is no `h` for "hex". Instead, use `b` to create binary data, followed by the `%hex(..)` function to convert it to hex. + +.Example + +[source,unlang] +---- +&reply.Reply-Message := "The random string output is %randstr(8a)" +---- + +.Output + +``` +The random string output is 4Uq0gPyG +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/rpad.adoc b/doc/antora/modules/reference/pages/xlat/rpad.adoc new file mode 100644 index 00000000000..2c11bb9261c --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/rpad.adoc @@ -0,0 +1,23 @@ += %rpad(, , ) + +Right-pad a string. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "123" + +&reply.Reply-Message := "Maximum should be %rpad(%{control.Tmp-String-0}, 11, '0')" +---- + +.Output + +``` +Maximum should be 12300000000 +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/string.adoc b/doc/antora/modules/reference/pages/xlat/string.adoc index 9933067c1a4..2c1ed1adc05 100644 --- a/doc/antora/modules/reference/pages/xlat/string.adoc +++ b/doc/antora/modules/reference/pages/xlat/string.adoc @@ -2,195 +2,21 @@ The following functions perform string manipulation. -== %concat(<&ref:[idx]>, ) - -Used to join two or more attributes, separated by an optional delimiter. - -.Return: _string_ - -In most cases, `%concat(...)` is only useful inside of a dynamically -expanded string. If you need to concatenate strings together in a policy, just use `+`. - -.Example - -[source,unlang] ----- -&control += { - &Tmp-String-0 = "aaa" - &Tmp-String-0 = "bb" - &Tmp-String-0 = "c" -} - -&reply += { - &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ', ')" - &Reply-Message = "%concat(%{control.Tmp-String-0[*]}, ',')" -} ----- - -.Output - -``` -aaa, bb, c -aaa,bb,c -``` - -.Using "+" -[source,unlang] ----- -string foo - -&foo += { "a", "c", "c", "d" } # abcd - -&foo += &control.Tmp-String-0[*] ----- - -== %explode(<&ref>, ) - -Split an string into multiple new strings based on a delimiter. - -This expansion is the opposite of `%concat( ... )`. - -.Return: _the number exploded list of strings_. - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := "bob.toba@domain.com" - -&control.Tmp-String-1 := "%explode(&control.Tmp-String-0, '@')" - -&reply.Reply-Message := "Welcome %{control.Tmp-String-1[0]}" ----- - -.Output - -``` -Welcome bob.toba -``` - -== %lpad(, , ) - -Left-pad a string. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := "123" - -&reply.Reply-Message := "Maximum should be %lpad(%{control.Tmp-String-0}, 11, '0')" ----- - -.Output - -``` -Maximum should be 00000000123 -``` - -== %rpad(, , ) - -Right-pad a string. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := "123" - -&reply.Reply-Message := "Maximum should be %rpad(%{control.Tmp-String-0}, 11, '0')" ----- - -.Output - -``` -Maximum should be 12300000000 -``` - -== %pairs(.[*]) - -Serialize attributes as comma-delimited string. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := { "This is a string", "This is another one" } -&reply.Reply-Message := "Serialize output: %pairs(&control.[*])" ----- - -.Output - -``` -Serialize output: Tmp-String-0 = "\"This is a string\", Tmp-String-0 = \"This is another one\"" -``` - -== %randstr( ...) - -Get random string built from character classes. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&reply.Reply-Message := "The random string output is %randstr(aaaaaaaa}" ----- - -.Output - -``` -The random string output is 4Uq0gPyG -``` - -== %tolower( ... ) - -Dynamically expands the string and returns the lowercase version of -it. This definition is only available in version 2.1.10 and later. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := "CAIPIRINHA" -&reply.Reply-Message := "tolower of %{control.Tmp-String-0} is %tolower(%{control.Tmp-String-0})" ----- - -.Output - -``` -tolower of CAIPIRINHA is caipirinha -``` - -== %toupper( ... ) - -Dynamically expands the string and returns the uppercase version of -it. This definition is only available in version 2.1.10 and later. - -.Return: _string_ - -.Example - -[source,unlang] ----- -&control.Tmp-String-0 := "caipirinha" -&reply.Reply-Message := "toupper of %{control.Tmp-String-0} is " + %toupper(%{control.Tmp-String-0}) ----- - -.Output - -``` -toupper of caipirinha is CAIPIRINHA -``` - -// Copyright (C) 2021 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +.String manipulation +[options="header"] +[cols="30%,70%"] +|===== +| Function | Description +| xref:xlat/concat.adoc[concat] | Concatenate strings with delimiters +| xref:xlat/explode.adoc[explode] | Split a string based on delimiters +| xref:xlat/length.adoc[length] | Get the length of a string +| xref:xlat/lpad.adoc[lpad] | Left pad a string +| xref:xlat/pairs.adoc[pairs] | Serialize a list of attributes to a string +| xref:xlat/rpad.adoc[rpad] | Right pad a string +| xref:xlat/randstr.adoc[randstr] | Return a random string based on input format +| xref:xlat/tolower.adoc[tolower] | Convert the input string to lowercase. +| xref:xlat/toupper.adoc[toupper] | Convert the input string to uppercase +|===== + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/tolower.adoc b/doc/antora/modules/reference/pages/xlat/tolower.adoc new file mode 100644 index 00000000000..1fac6f0d7fd --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/tolower.adoc @@ -0,0 +1,25 @@ += %tolower( ... ) + +Dynamically expands the string and returns the lowercase version of +it. + +The lowercase operation is done using the current locale. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "CAIPIRINHA" +&reply.Reply-Message := "tolower of %{control.Tmp-String-0} is %tolower(%{control.Tmp-String-0})" +---- + +.Output + +``` +tolower of CAIPIRINHA is caipirinha +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/toupper.adoc b/doc/antora/modules/reference/pages/xlat/toupper.adoc new file mode 100644 index 00000000000..50167a0e4e6 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/toupper.adoc @@ -0,0 +1,25 @@ += %toupper( ... ) + +Dynamically expands the string and returns the uppercase version of +it. + +The uppercasecase operation is done using the current locale. + +.Return: _string_ + +.Example + +[source,unlang] +---- +&control.Tmp-String-0 := "caipirinha" +&reply.Reply-Message := "toupper of %{control.Tmp-String-0} is " + %toupper(%{control.Tmp-String-0}) +---- + +.Output + +``` +toupper of caipirinha is CAIPIRINHA +``` + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS.