From: nolade Date: Fri, 9 May 2025 17:05:32 +0000 (-0400) Subject: docs: xlat string functions reorganized into sub-dir `str`. Updated nav file links... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f4463ff48c4ac6aeca21b9dbdcb80e6941df0c72;p=thirdparty%2Ffreeradius-server.git docs: xlat string functions reorganized into sub-dir `str`. Updated nav file links and added ./string/index.adoc file and relevant links to sub-sections. --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index e3231f80830..b9ffe7a43ac 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -72,6 +72,7 @@ *** xref:xlat/alternation.adoc[Alternation Syntax] *** xref:xlat/conversion.adoc[Data Conversion] *** xref:xlat/deprecated.adoc[Deprecated Functions] + *** xref:xlat/file/index.adoc[File Handling] **** xref:reference:xlat/file/escape.adoc[escape] **** xref:xlat/file/exists.adoc[exists] @@ -79,21 +80,24 @@ **** xref:xlat/file/rm.adoc[rm] **** xref:xlat/file/size.adoc[size] **** xref:xlat/file/tail.adoc[tail] + *** xref:xlat/function.adoc[Function Syntax] *** xref:xlat/hash.adoc[Hashing] + *** xref:xlat/interpreter.adoc[Interpreter State and Debugging] *** 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/str/index.adoc[String Handling] +**** xref:xlat/str/concat.adoc[Concatenation] +**** xref:xlat/str/split.adoc[Split Strings] **** xref:xlat/builtin.adoc#length[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[Convert to Lowercase] -**** xref:xlat/toupper.adoc[Convert to Uppercase] +**** xref:xlat/str/lpad.adoc[Left Pad] +**** xref:xlat/str/rpad.adoc[Right Pad] +**** xref:xlat/str/rand.adoc[Random Strings] +**** xref:xlat/str/lower.adoc[Convert to Lowercase] +**** xref:xlat/str/upper.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/pairs.adoc b/doc/antora/modules/reference/pages/xlat/pairs.adoc deleted file mode 100644 index e87893a0bd4..00000000000 --- a/doc/antora/modules/reference/pages/xlat/pairs.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= %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/concat.adoc b/doc/antora/modules/reference/pages/xlat/str/concat.adoc similarity index 85% rename from doc/antora/modules/reference/pages/xlat/concat.adoc rename to doc/antora/modules/reference/pages/xlat/str/concat.adoc index 249481eedff..e7c5bc8affd 100644 --- a/doc/antora/modules/reference/pages/xlat/concat.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/concat.adoc @@ -2,7 +2,7 @@ Used to join two or more attributes, separated by an optional delimiter. -This expansion is the inverse of xref:xlat/explode.adoc[explode]. +This expansion is the inverse of xref:xlat/str/explode.adoc[explode]. .Return: _string_ @@ -42,5 +42,5 @@ foo += { "a", "c", "c", "d" } # abcd foo += control.Tmp-String-0[*] ---- -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Copyright (C) 2025 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/str/index.adoc b/doc/antora/modules/reference/pages/xlat/str/index.adoc new file mode 100644 index 00000000000..95babc0d2d4 --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/str/index.adoc @@ -0,0 +1,22 @@ += String manipulation + +The following functions perform string manipulation. + +.String manipulation +[options="header"] +[cols="30%,70%"] +|===== +| Function | Description +| xref:xlat/str/concat.adoc[concat] | Concatenate strings with delimiters +| xref:xlat/str/split.adoc[split] | Split a string based on delimiters +| xref:xlat/builtin.adoc#length[Length] | Returns the size of the string (strlen) +| xref:xlat/str/lpad.adoc[lpad] | Left pad a string +| xref:xlat/str/rpad.adoc[rpad] | Right pad a string +| xref:xlat/str/rand.adoc[rand] | Return a random string based on input format +| xref:xlat/str/lower.adoc[lower] | Convert the input string to lowercase. +| xref:xlat/str/upper.adoc[upper] | Convert the input string to uppercase +|===== + +// Copyright (C) 2025 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/str/lower.adoc b/doc/antora/modules/reference/pages/xlat/str/lower.adoc new file mode 100644 index 00000000000..73dc0da02bc --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/str/lower.adoc @@ -0,0 +1,24 @@ += %str.lower( ... ) + +Returns the lowercase version of the input. + +The lowercase operation is done using the current locale. + +.Return: _string_ + +.Example + +[source,unlang] +---- +control.Tmp-String-0 := "CAIPIRINHA" +reply.Reply-Message := "lowercase of %{control.Tmp-String-0} is %str.lower(control.Tmp-String-0)" +---- + +.Output + +``` +lowercase of CAIPIRINHA is caipirinha +``` + +// Copyright (C) 2025 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/str/lpad.adoc similarity index 84% rename from doc/antora/modules/reference/pages/xlat/lpad.adoc rename to doc/antora/modules/reference/pages/xlat/str/lpad.adoc index 32c1f77e7dd..d3e40842d6d 100644 --- a/doc/antora/modules/reference/pages/xlat/lpad.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/lpad.adoc @@ -19,5 +19,5 @@ reply.Reply-Message := "Maximum should be %str.lpad(%{control.Tmp-String-0}, 11, Maximum should be 00000000123 ``` -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Copyright (C) 2025 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/str/rand.adoc similarity index 71% rename from doc/antora/modules/reference/pages/xlat/randstr.adoc rename to doc/antora/modules/reference/pages/xlat/str/rand.adoc index fe8d7efebea..bc9c7688ed4 100644 --- a/doc/antora/modules/reference/pages/xlat/randstr.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/rand.adoc @@ -26,13 +26,13 @@ preceded by an integer repetition count: | 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. +There is no `h` for "hex". Instead, use `b` to create binary data, and then use the `%hex(..)` function to convert the output to hex. -.Example +.Example of a random string [source,unlang] ---- -reply.Reply-Message := "The random string output is %str.rand(8a)" +reply.Reply-Message := "The random string output is %str.rand('8a')" ---- .Output @@ -41,5 +41,18 @@ reply.Reply-Message := "The random string output is %str.rand(8a)" The random string output is 4Uq0gPyG ``` -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +.Example of conversion to hex + +[source,unlang] +---- +reply.Reply-Message := "The random string output is %hex(%str.rand('1b'))" +---- + +.Output + +``` +The random string output is ad +``` + +// Copyright (C) 2025 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/str/rpad.adoc similarity index 84% rename from doc/antora/modules/reference/pages/xlat/rpad.adoc rename to doc/antora/modules/reference/pages/xlat/str/rpad.adoc index 757308d07a7..1303e4a482c 100644 --- a/doc/antora/modules/reference/pages/xlat/rpad.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/rpad.adoc @@ -19,5 +19,5 @@ reply.Reply-Message := "Maximum should be %str.rpad(%{control.Tmp-String-0}, 11, Maximum should be 12300000000 ``` -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Copyright (C) 2025 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/str/split.adoc similarity index 65% rename from doc/antora/modules/reference/pages/xlat/explode.adoc rename to doc/antora/modules/reference/pages/xlat/str/split.adoc index bf174aef551..74ca351333c 100644 --- a/doc/antora/modules/reference/pages/xlat/explode.adoc +++ b/doc/antora/modules/reference/pages/xlat/str/split.adoc @@ -2,7 +2,7 @@ Split an string into multiple new strings based on a delimiter. -This expansion is the inverse of xref:xlat/concat.adoc[concat]. +This expansion is the inverse of xref:xlat/str/concat.adoc[str.concat]. .Return: _the list of strings_. @@ -12,7 +12,7 @@ This expansion is the inverse of xref:xlat/concat.adoc[concat]. ---- control.Tmp-String-0 := "bob.toba@domain.com" -control.Tmp-String-1 := "%str.split(control.Tmp-String-0, '@')" +control.Tmp-String-1 := %str.split(control.Tmp-String-0, '@') reply.Reply-Message := "Welcome %{control.Tmp-String-1[0]}" ---- @@ -23,5 +23,5 @@ reply.Reply-Message := "Welcome %{control.Tmp-String-1[0]}" Welcome bob.toba ``` -// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Copyright (C) 2025 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/str/upper.adoc b/doc/antora/modules/reference/pages/xlat/str/upper.adoc new file mode 100644 index 00000000000..3dbb7e359be --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/str/upper.adoc @@ -0,0 +1,24 @@ += %str.upper( ... ) + +Returns the uppercase version of the input. + +The uppercase operation is done using the current locale. + +.Return: _string_ + +.Example + +[source,unlang] +---- +control.Tmp-String-0 := "caipirinha" +reply.Reply-Message := "uppercase of %{control.Tmp-String-0} is " + %str.upper(control.Tmp-String-0) +---- + +.Output + +``` +uppercase of caipirinha is CAIPIRINHA +``` + +// Copyright (C) 2025 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 deleted file mode 100644 index 57730bd4b36..00000000000 --- a/doc/antora/modules/reference/pages/xlat/string.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= String manipulation - -The following functions perform string manipulation. - -.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/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 deleted file mode 100644 index df503742ff0..00000000000 --- a/doc/antora/modules/reference/pages/xlat/tolower.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= %str.lower( ... ) - -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 %str.lower(%{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 deleted file mode 100644 index dd0288bf4ac..00000000000 --- a/doc/antora/modules/reference/pages/xlat/toupper.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= %str.upper( ... ) - -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 " + %str.upper(%{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.