From: Alan T. DeKok <aland@freeradius.org>
Date: Fri, 8 Jul 2022 15:07:43 +0000 (-0400)
Subject: update documentation on string escaping, etc.
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=146ed9e43945468b3e819cdade602fe8d3c84ab6;p=thirdparty%2Ffreeradius-server.git

update documentation on string escaping, etc.
---

diff --git a/doc/antora/modules/reference/pages/type/cast.adoc b/doc/antora/modules/reference/pages/type/cast.adoc
index 0a58066d0c6..7349feedec2 100644
--- a/doc/antora/modules/reference/pages/type/cast.adoc
+++ b/doc/antora/modules/reference/pages/type/cast.adoc
@@ -117,6 +117,15 @@ string, and assigning the resulting value to the `string`.  For
 Casting a `string` value to another data type means _parsing_ the
 string as that data type.
 
+See xref:types/string/double.adoc[double-quoted strings] for examples
+of how double-quoted strings are used.
+
+==== Other Data Types
+
+Other data types such as `ethernet`, etc. can generally be cast
+to/from `octet`, and printed to/from `string`.  Most other casts do
+not make sense, and will not work.
+
 === Expressions
 
 Unlang xref:unlang/expression.adoc[expressions] can use casts, too, as
diff --git a/doc/antora/modules/reference/pages/type/string/double.adoc b/doc/antora/modules/reference/pages/type/string/double.adoc
index fb8ba479bb7..9c4e7d41ee9 100644
--- a/doc/antora/modules/reference/pages/type/string/double.adoc
+++ b/doc/antora/modules/reference/pages/type/string/double.adoc
@@ -100,6 +100,30 @@ because it is already a string.
 The output strings here are completely different than for the previous
 examples.  The output data type is `octets`, and not `string`.
 
+If the goal is to have the _raw_ `octets` data inserted into a
+`string`, you must use the `%{string:...}` expansion.  This expansion
+will copy the input `octets` value to a the output, changing the data
+type to `string`.  The value is left alone.
+
+.Example of casting to raw 'octets'
+[source,unlang]
+----
+"User-Name is %{Tmp-Octets-0}"
+"User-Name is %{string:%{Tmp-Octets-0}}"
+----
+
+if the `&Tmp-Octets-0` attribute has value `0x666f6f` (`foo`)
+
+In the first expansion, the resulting output is `User-Name is
+0x666f6f`.  In the second expansion, the resulting output is
+`User-name is foo`.
+
+Note that placing raw `octets` data into a string may allow for binary
+data to be inserted into what should be a printable string.  Any uses
+of the string will result in the non-printable data being escaped as
+`\000` or other methods such a `\n`, depending on how and wheere the
+string is being used.
+
 .Examples
 
 `"word"` +
diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc
index 28677d368cb..0c7c6593d62 100644
--- a/doc/antora/modules/reference/pages/xlat/builtin.adoc
+++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc
@@ -135,26 +135,27 @@ The tag value of the second instance of Tunnel-Server-Enpoint is 192.0.5.2
 
 === %{string:<data>}
 
-Convert input to a string if (possible).  For _octets_ type attributes, this
-means interpreting the data as a UTF8 string, and inserting octal escape
-sequences where appropriate.
+Convert input to a string if (possible).  For _octets_ type
+attributes, this means interpreting the data as a UTF8 string.  Any
+non-printable characters are left in place.
 
 For other types, this means printing the value in its _presentation_ format,
 i.e. dotted quads for IPv4 addresses, link:https://en.wikipedia.org/wiki/ISO_8601[ISO 8601]
 time for date types, enumeration values for attributes such as `radius.Service-Type` etc.
 
-.Return: _string_
+In practice, the only real use of this expansion is to insert `octets`
+data types into a `string`.  For other data types, using
+`%{string:...}` is not necessary.  For example, for any data type
+other than `octets`, the following equivalency holds true.
+
+See xref:types/string/double.adoc[double-quoted strings] and
+xref:type/cast.adoc[casting] for examples of how strings are used.
 
-.String interpolation using the raw octets value of Tmp-Octets-0, and the stringified version
+.String expansion equivalents
 ====
 [source,unlang]
 ----
-update control {
-    &Tmp-Octets-0 := 0x7465737431
-}
-update reply {
-    &Reply-Message := "The string value of %{control.Tmp-Octets-0} is %{string:%{control.Tmp-Octets-0}}"
-}
+"foo" + (string)&Bar == "foo%{Bar}"
 ----
 ====