The string Data Type
The string data type is intended to printable strings. However,
strings in the server are binary safe. It is possible to assign any
value to them, including binary data, embedded NUL (0) characters,
etc. Assigning a value with an embedded NUL character results in
the string containing the NUL character. The string is not
terminated at the NUL.
When a string is printed to a text form, any binary data is escaped, so that the output does not contain embedded binary data. The output is then valid text, usually ASCII or UTF-8.
That output can then be parse to create the original string, with the embedded binary data.
There are a number of different ways to parse strings, each of which have their different use-cases.
Single Quoted Strings
A single quoted string uses the '
character to delineate the string.
The string does not support escaping its contents, except for allowing
\', so that the string can contain the quotation character.
However, we recommend using triple quoted
strings instead, if the string needs to contain the quotation
character.
Double Quoted Strings
A double quoted string uses the "
character to delineate the string.
The string supports the usual escaping of its contents, such as \\r,
\\n, and \\" in order to embed a quotation character in the
string. However, we recommend using
triple quoted strings instead, if the
string needs to contain the quotation character.
Double-quoted strings can also contain dynamic expansions.
Back-Quoted Strings
A back quoted string uses the \`
character to delineate the string.
The string supports the same escaping rules as for double-quoted
strings, including allowing the use of \\` to embed the quotation
character in the string.
This string format is permitted only in a small number of situations,
typically in unlang assignments. Even then, using this format is
not recommended, and the %exec(…) function should be used instead.
Support for back-quoted strings is likely to be removed in a future release.
Regular Expression Strings
Regular expression strings use the / character for string quotes,
and otherwise are treated exactly the same as a
double quoted string.
This string format is permitted only in unlang conditional
expressions, where the operator is a regular expression operator such
as =~ or !~.
Unquoted strings
An unquoted string is just a piece of
text without a quotation character, e.g. foo.
While the parser tries to be flexible with reading the configuration files, it is not perfect. Using ambiguous syntax in the configuration files will likely cause the server to complain that is unable to parse the data.
The solution is to properly quote strings, instead of relying on the parser to implicitly parse text words.
Triple quoted strings
Triple quoted strings are a special case of single quoted strings or double quoted strings. They are parsed exactly the same as the base string type, with one exception: any quotation character inside of the tripled quoted string does not need to be escaped.
Triple quoted strings do not support spanning multiple lines. That limitation is likely to be fixed in a future release.